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How the BASIC Interpreter Works 



The BASIC interpreter is one of the most important parts of a computer. 
The interpreter is responsible for the following tasks, among others: 

1) Allows the user to enter data through the keyboard either as a 
DIRECT mode command or stored as a BASIC program line. 

2) If the data entered is a DIRECT mode command statement, the 
BASIC interpreter calls the proper routines to tokenize the 
command statement and execute the command statement 

3) If the data entered is a BASIC program line, the BASIC 
interpreter calls the routines necessary to tokenize the program 
line and store it in memory. 

4) If the program stored in memory is to be RUN, the BASIC 
interpreter calls the necessary routines to execute the individual 
command statements in the BASIC program. 

Now that we generally understand what the BASIC interpreter is supposed 
to do, let's take a closer look at how it works. 

Upon powerup or reset, the 8502 microprocessor in the C-128 starts 
executing the RESET routine stored in locations $FFFC and $FFFD. This 
address is called the RESET Vector. It normally holds the address of the 
RESET routine at $FF3D. However, like any other vector, the address 
stored here can be changed to point to any other address that the user 
wishes. In this case, it applies only to the reset button. 

The RESET routine takes care of initializing the C-128 and finishes by 
calling the routine that displays the startup message to the screen. Once this 
has been done, control is turned over to the BASIC interpreter loop. 

Let's mention another routine before we continue. It's the IRQ (Interrupt 
ReQuest) routine. Its address is stored in the IRQ Vector at locations $FFFE 
and $FFFF. The address that is normally stored here when the computer is 
initialized is $FF17, which eventually jumps through an indirect vector 
located at $0314. This vector can point to several things, such as the tape 
I/O routines, but normally this vector points to $FA65 — the normal entry 
point for the Interrupt ReQuest (IRQ) routine. 
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Every l/60th of a second, the IRQ routine scans the keyboard to see if a key 
has been pressed. If a key is pressed, the ASCII value which corresponds 
to that key is stored in the keyboard buffer to await removal by BASIC. 

Once the key value has been stored by the IRQ routine in the buffer, the 
BASIC interpreter can later retrieve the ASCII value and store it into the 
INPUT buffer. The process continues until the ASCII value for the 
<RETURN> key (or <SHlPT xRETURN >) is detected. 

When the value for the <RETURN> key is detected, the BASIC interpreter 
checks to see if the first character in the statement is a number. If it's a 
number, the BASIC interpreter calls the necessary routines to tokenize and 
store the statement in memory as a BASIC program line. However, if the 
first character is not a number, then the BASIC interpreter calls the 
necessary routines to tokenize the statement and then execute it as a 
DIRECT mode statement 

For instance, if you type the statement PRINT without a preceding line 
number and then press the <RETURN> key, the statement is immediately 
tokenized and executed. This will PRINT a blank line to the screen. 
However, if you type the same PRINT statement preceded by a number and 
press the <RETURN> key, the statement is tokenized and stored in memory 
as a BASIC program line. 

When the BASIC RUN command is used to execute the BASIC program 
stored in memory, the BASIC interpreter is responsible for calling the 
different routines that search for the command tokens and execute the 
commands that are specified. 

The BASIC interpreter must keep track of many values and addresses in 
order to RUN a program correctly. It uses what is known as a stack to keep 
track of the various parameters and addresses. This can be thought of as a 
stack of papers piled on top of each other, each sheet containing a single 
value. Because the stack is such an important concept in the BASIC 
interpreter's operation, we'll go into much greater detail on the stack's 
operation in the next section. 
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1.1 The Pseudo Stack in the C-128 



The term stack is used to describe an area of memory set aside as a work 
area for storing the parameters necessary for the operation of a routine. In 
the C-128, there are two such stacks: the processor stack, located at $0100 - 
$01FF, and the pseudo stack, located at $0800 - $09FF. 

The processor stack is used by the 8502 when executing machine language 
instructions such as PHA, which pushes (saves) the value in the accumulator 
onto the processor stack, and P LA, which pulls (retrieves) the topmost 
value from the stack and places it into the accumulator. Each time an 
operation is performed using the stack, an internal register in the 8502 called 
the Stack Pointer is automatically incremented or decremented so that it 
points to the next available stack location to be used. For example, when a 
pha is executed, the stack pointer is decremented. When a PLA is executed, 
the stack pointer is incremented. If the stack pointer should get too full 
when the processor stack is used, then a ’formula TOO complex’ 
error is displayed. 

The second stack is the pseudo stack, which is used by the BASIC routines 
GOSUB, FOR/NEXT, and DO/LOOP. Each of these routines stores a 
different set of parameters that it needs to accomplish its respective task. 
The stack pointer for the pseudo stack is located in memory at $7D and $7E. 

However, unlike the processor’s stack pointer, the pseudo stack pointer is 
not automatically updated when information is stored or retrieved from it. 
The individual routines that use the pseudo stack are responsible for 
updating the stack pointer. 

For example, if a routine needs to store a parameter on the pseudo stack, it 
will store the value to the pseudo stack and then decrement die pseudo stack 
pointer to point to the next available memory location on the stack. If a 
routine needs to get a parameter from the pseudo stack, the pseudo stack 
pointer is incremented and the value that it points to is retrieved. If the 
pseudo stack pointer should get too full when the processor stack is used, 
then an 'OUT OF MEMORY ' or ' FORMULA TOO COMPLEX' error is 
displayed, depending on when the stack overflow occurred. 

Now let's discuss how the GOSUB/RETURN, for/next, and DO/LOOP 
command routines use the pseudo stack to accomplish their individual jobs. 



5 





Abacus Software 



C-128 BASIC 7.0 Internals 



The machine language routines for these commands can be found in the 
BASIC ROMs at the following locations: 

Routine Location 

GOSUB /RETURN $59CF and $5262 

FOR/NEXT $4DF9 and $57F4 

DO/ LOOP $5FE0 and $608 A 



1.1.1 How GOSUB/return Uses the Pseudo Stack 



The GOSUB/RETURN command combination is used when you want to 
perform a subroutine that is identified by another line number in a BASIC 
program, and then return to your original line number in the same program. 
Here is an example of the GOSUB/RETURN command combination: 

10 PRINT "HELLO" 

20 GOSUB 50 
30 PRINT "EVERYBODY" 

40 END 

50 PRINT "THERE" 

60 RETURN 

When the program is running and the BASIC interpreter comes across the 
token for GOSUB, it will call the GOSUB routine at $59CF . 

The GOSUB routine at $59CF stores five bytes of information on the pseudo 
stack that are to be used by the RETURN command routine at $5262. These 
five bytes of information are stored in the following order, starting at the 
memory location pointed to by the Top Of Stack pointer (TOS) and working 
downward towards the bottom of the stack at $0800: 
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BYTE 


FREE STACK SPACE 


$04 


Token value for the GOSUB command ($8D) 


$03 


LSB of the HEX value for the line number to RETURN to 


$02 


MSB of the HEX value for the line number to RETURN to 


$01 


LSB of the address of the GOSUB statement 


$00 


MSB of the address of the GOSUB statement 



$0800 



TOS 



TOS = Top Of Stack pointer (Pseudo stack pointer) 

Note: The address that is stored in Bytes $00 and $01 points 
to the first byte after the token for the GO SUB 
command. 

After the information has been stored on the stack, the program continues 
execution at the line number specified after the GO SUB command, and 
continues until the token for the RETURN command ($8E) is encountered. 

When a RETURN command is encountered, the five bytes of information 
that were stored on the pseudo stack by the GOSUB routine are used by the 
RETURN routine. This routine searches for the first occurrence of the 
GOSUB token and then retrieves the information that was stored there , but 
in the reverse order. This information is then used to return the program 
execution to the place where the GOSUB command was used to continue the 
program at the next statement or line number. 
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1.1.2 How DO/LOOP uses the Pseudo Stack 



The DO /LOOP command combination is used when you want to execute a 
certain area of the BASIC program over and over. An example of the 
DO /LOOP command follows: 

10 DO 

20 PRINT "HELLO THERE EVERYBODY" 

30 LOOP 

When the program is running and the BASIC interpreter comes across the 
token for DO, it calls the DO routine at $5FE0. The DO routine stores five 
bytes of information on the pseudo stack that are to be used by the LOOP 
command routine at $608 A. 

These five bytes of information are stored on the pseudo stack starting at the 
memory location pointed to by the Top Of Stack pointer (TOS), and 
working downward towards the bottom of the stack at $0800: 



$0800 



BYTE 


FREE STACK SPACE 


$04 


Token value for the DO command ($EB) 


$03 


LSB of the HEX value for the line number to LOOP to 


$02 


MSB of the HEX value for the line number to LOOP to 


$01 


LSB of the address of the DO statement 


$00 


MSB of the address of the DO statement 



TOS = Top Of Stack pointer (Pseudo stack pointer) 

Note: The address that is stored in Bytes $00 and $01 points 
to the first byte after the token for the DO command. 
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After the information has been stored on the stack, the program continues 
executing with the next line number until the token for the LOOP command 
($EC) is encountered. 

When a LOOP command is encountered, the five bytes of information that 
were stored on the pseudo stack by the DO routine at $5FE0 are used by the 
LOOP routine at $608 A. This routine searches for the first occurrence of the 
DO token ($EB) and then retrieves the information that was stored there, but 
in the reverse order. This information is then used to loop the program 
execution to the place where the DO command is located. 



1.1.3 How for/next uses the Pseudo Stack 



The for/next command combination is used when you want to execute a 
certain area of the BASIC program a specific number of times. This 
command combination can also be used as a delay loop. An example of 
FOR/NEXT: 

10 FOR X=1 TO 10 

20 PRINT "HELLO THERE EVERYBODY" 

30 NEXT 

When the program is running and the BASIC interpreter comes across the 
token for FOR, it will call the FOR routine at $5DF9. The FOR routine stores 
eighteen bytes of information on the pseudo stack. 

These eighteen bytes of information are stored on the pseudo stack in the 
following order starting at the memory location that is pointed to by the Top 
Of Stack pointer (TOS) and working downward towards the bottom of the 
stack at $0800: 
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BYTE 


FREE STACK SPACE 


$11 


Token value for the FOR command ($81) 


$10 


LSB of the address of the variable name’s descriptor 


$0F 


MSB of the address of the variable name’s descriptor 


$0E 


EXPonent of the floating point STEP value 


-c/> 

o 

O 


Ml of the floating point STEP value 


$oc 


M2 of the floating point STEP value 


$0B 


M3 of the floating point STEP value 


$0A 


M4 of the floating point STEP value 


$09 


Sign of the STEP value ($01 = Positive, $FF = Negative) 


$08 


EXPonent of the floating point variable limit value 


$07 


Ml of the floating point variable limit value 


$06 


M2 of the floating point variable limit value 


$05 


M3 of the floating point variable limit value 


$04 


M4 of the floating point variable limit value 


$03 


LSB of the line number that the FOR statement is on 


$02 


MSB of the line number that the FOR statement is on 


$01 


MSB of the address of the next statement in the program 


$00 


LSB of the address of the next statement in the program 



$0800 



TOS 



TOS =Top Of Stack pointer (Pseudo stack pointer) 
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After the information has been stored on the stack, the program continues 
executing with the next line number until the token for the NEXT command 
($ 82 ) is encountered. 

When a NEXT command is encountered, the eighteen bytes of information 
that were stored on the pseudo stack by the FOR routine are used by the 
next routine. This routine searches for the first occurrence of the FOR 
token ($ 81 ) and then retrieves the information that was stored there, but in 
the reverse order. This information is then used to determine whether the 
for/next loop is finished or whether it needs to be executed again. 
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1.2 Program Storage in the C-128 



The format of a program that has been stored in C-128 memory is very 
similar to the format stored by the other home computers that Commodore 
produces. However, the C-128 does tokenize some of the BASIC 
commands and functions differently. 

In the C-128, the added commands and functions make it necessary to use 
dual token commands and functions. Dual token commands and functions 
consist of a two byte token, with the first byte value being either a $CE or 
$FE. An example of a dual token command is the command PLAY. This 
command when tokenized and stored in memory consists of the two bytes 
$FE and $04. This is indeed different than a single token command like 
PRINT, which is tokenized as a one byte value of $99 (See Appendix B). 

The start of BASIC text usually begins at location $1C01 in RAM bank 0. 
This is the starting address that will be used for the examples discussed in 
this text 

For the following discussion, it is easier to explain the storage of a BASIC 
program if an example program is used. Consequently, turn your computer 
on and type in the following short BASIC program: 

10 PRINT "HELLO" 

20 END 

After you have entered the program, enter the MONITOR and type 
M 01C00 01C17. This displays a memory dump of the area of memory in 
RAM bank 0 where the BASIC program was stored. Your screen will look 
like this: 



00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E OF 



>01C00 : 00 0E 1C 0A 00 99 22 48 45 4C 4C 4F 22 00 14 1C 
>01C10 : 14 00 80 00 00 00 



The first thing that can be found stored at $1C00 is the single zero byte 
which indicates the end of a BASIC line. This memory location must 
always be set to zero when storing a BASIC program, or else a ' SYNTAX ' 
error is issued when you try to RUN the program. 
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Next, stored in locations $1C01 and $1C02 are the LSB (Least Significant 
Bit) and MSB (Most Significant Bit) , respectively, of the line link address 
that points to the line link of the next program line. In our example, 
locations $1C01 and $1C02 point to location $1C0E. 

Following these two bytes at $1C03 and $1C04 are the LSB and MSB 
value, respectively, of the program line number entered with the BASIC 
program line. In our example, the line number value is $000A or 10. 

Following the program line number is the tokenized BASIC program line 
that represents the original BASIC program line. Each keyword is converted 
to a one or two byte token and then stored in memory. However, the text 
that is to be printed, which was enclosed in quotes when the program line 
was typed in, is only converted to its HEX equivalent and stored in 
memory. 

The first program line is represented by the following partial memory dump: 
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 



>1C00 : 00 0E 1C 0A 00 99 22 48 45 4C 4C 4F 22 00 

The byte following the MSB of the program line number at location $1C05 
is the tokenized value for the command PRINT ($99). The seven bytes that 
follow the token for print from location $1C06 to $1C0C are the ASCII 
values for the quotes and letters of the text to be printed, "HELLO". A 
single zero byte is stored at location $1C0D to indicate the end of the 
program line. 

Now let's see how the last program line looks in memory: 

0E OF 10 11 12 13 14 15 



>1C0D : 14 1C 14 00 80 00 00 00 

As you can see, the next BASIC program line starts at locations $1C0E and 
1C0F. These are the LSB and MSB of the line link address that points to the 
next line link address of the next program line. In this case, the address is 
$104. 

The next two bytes, locations $100 and $1C1 1, are the LSB and MSB, 
respectively, of the second program line's line number. Here the line 
number is $0014, or decimal 20. 
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Next, the token for the END command is stored at $102 ($80). Since the 
END command is the only thing in this BASIC program line, the end of line 
marker ($00) is stored at location $103. 

This sequence of bytes continues until the last program line is reached. 
Since line 20 is the last program line, two consecutive zero bytes are stored 
at locations $104 and $105. This constitutes the end of BASIC program 
marker. 

The address of the byte after the end of BASIC program marker is stored in 
locations $1210 and $1211. The address stored in these locations is used by 
the various routines such as the LOAD, SAVE, and renumber routines so 
that the end of the BASIC program can be determined. These locations are 
updated each time a program line is inserted or deleted. 

Let's take a moment to illustrate with a simple diagram how the line links, 
etc., are used: 



Start Of BASIC 

Line link Address 
BASIC line # 



| BASIC 

1 i 



End of line 

Line link address 
BASIC line # 



OIL H L H 






TEXT 



1 



JL 



End of line 
End of 
program flag 



0 I L I H |l ~ h! TEXT 



0 0 0 



■> 



K 



>- 



Pointer to next 
Line link address 



Pointer to next 
Line link address 



Figure 1.2 
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1.2.1 Resurrecting a BASIC Program 



Now that we have seen how a BASIC program line is stored in memory, 
let's see what happens when we use the command NEW and some ways to 
unNEW a program that has been accidently "erased" from memory. 

When you type in the command NEW and press <RETURN>, two things 
happen. First, two zero bytes are stored at the beginning of the BASIC text 
memory. Normally these locations are $1C01 and $1C02. Consequently, a 
memory dump of die area of memory where the BASIC program was stored 
would look like this: 

00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E OF 



>01C00: 00 00 00 0A 00 99 22 48 45 4C 4C 4F 22 00 15 1C 
>01C10: 14 00 80 00 00 00 

Next, the end of BASIC pointer at $1210 and $1211 is updated to point to 
one byte past the last zero byte that was just written. So the pointer is 
updated to $1C04. The address that locations $1210 and $1211 would now 
point to would be location $1C04. 

That is really all that happens when you use the NEW command. The 
previous BASIC program is not erased. Therefore, if the first line link 
address can be restored and the program lines linked together, the BASIC 
program can be unNEWed. 

There are many ways of accomplishing this, but two methods are very 
simple to use. Due to some software quirks in the BASIC 7.0 ROMs, they 
are available to everyone. First, type in the following BASIC program: 

10 PRINT "HELLO” 

20 END 

Now type NEW and press <RETURN>. Type LIST and press <RETURN> 
to verify that the program is really gone — or so we think. Now type in the 
following statement in the DIRECT mode and press <RETURN>: 

POKE DEC ( " ICO 1 " ) , 1 : RENUMBER 

Now type LIST and press <RETURN> to verify that the BASIC program 
has really returned. "Amazing!" you say. Well, now try the next method. 
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Since the program has returned, make it disappear again with the NEW 
command. Again type LIST and press <RETURN> to verify that it is 
indeed gone. Now type in the following statement in the DIRECT mode and 
press <RETURN>: 

POKE DEC (" 1C01") , 1 : DELETE 0 

Now type LIST and press <RETURN> and again the BASIC program has 
been returned. How the unNEW is accomplished is hidden in the ROMs and 
can be found in the ROM listing under the routines for the renumber and 
DELETE commands. 



1.2.2 Recovering from a System "Crash” 



Occasionally the C-128 will hang up, such as is the case when a SYS to a 
wrong address is executed and puts die microprocessor into an infinite loop. 
When this happens, there are four ways to recover from the crash: 

1) Turn the computer off and then on. 

2) Press the reset button and use the unNEW examples in Section 

1 . 2 . 1 . 

3) Press the <RUN/STOP><RESTORE> key combination. 

The fourth way you might recover from a system crash is outlined below: 

1) Depress and hold down the <RUN/STOP> key. 

2) While still holding down the <RUN/STOP> key, press the 
RESET button on die right side of the 128 and release it. 

3) After you see that the computer has powered up in the machine 
language monitor, release the <RUN/STOP> key. 

4) Check to ensure that location $0A04 has a $C1 in it to ensure 
that the BASIC IRQ, etc., has been initialized. If it has a $C0 
in it, change it to $C1. 

5) Type an X and press <RETURN> to return to BASIC. 

6) Type in LIST and press <RETURN> to list the recovered 
program. 
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1.3 Variable Storage Format in the C-128 



The way the C-128 handles its variables is not too much different than the 
way that the C-64 handles its variables. However, in the 128, the zero page 
pointers have been moved and the variables themselves are stored in RAM 
BANK 1 instead of being stored immediately following the BASIC text, as 
it’s done in the 64. This is a distinct advantage to the BASIC programmer. 
With the 128, if a program stops due to a ' SYNTAX ' error or any other 
reason short of crashing the computer, the programmer can edit the line that 
is causing the problem and restart the program with a single GOSUB or 
GOTO command. Unlike the 64, this will not destroy the variable values that 
were stored in memory between the time the program started running and 
the time it crashed. This is the main difference in the way the 128 and die 64 
handle their variables. Now that we have covered the difference between the 
way that the 64 and 128 handle their variables, let’s move on to discuss the 
actual format used by the 128 to store variables. 

In the 128, as in the 64, there are three categories of variables: Simple, 
Complex, and Function variables. The Simple and Complex variables can 
be broken down into three types: Floating Point (FP), Integer, and String 
variables. However, Function variables can only be Floating Point type. 

Each variable is allocated a seven byte descriptor in RAM BANK 1 starting 
at $0400 to indicate the type of variable (the value of the variable or length 
of the variable if it is a string, and the address of the variable in RAM 
BANK 1, if the variable is a string). 

You assign each variable a name. A variable name may consist of one or 
two characters, and include any alphanumeric character (as long as the first 
character of the variable name is a letter, not a number). If the first character 
of the variable name is found to be a number by the BASIC interpreter, a 
' SYNTAX ' error will occur. 

Also, if the variable name is followed by a percent sign (%) or a dollar sign 
($), it is defined as an Integer or String variable, respectively. However, if 
die variable name is not followed by either % or $, the variable is designated 
as a Floating Point variable. 

There are a few variable names that are reserved exclusively for the use of 
the 128's operating system. These variable names are as follows: DS, DS$, 
EL, ER, ERR$, ST, Tl, Tl$. Also, any variable name that has a reserved 
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keyword imbedded in it cannot be used. For instance, you cannot use a 
variable name such as 'TO' because this is one of the reserved keywords of 
the BASIC operating system. 

After a variable name has been designated, the BASIC operating system 
evaluates the name to determine if it is valid. If the variable name is invalid, 
a ' SYNTAX ' error will occur. However, if the variable name is valid, bit 
seven of one, both, or neither of the characters in the variable name is set to 
indicate which of the three types the variable is. Let's take a moment to 
clarify how the type of variable is represented in the variable name. 

1) If the variable is a Floating Point variable, the values stored in 
Bytes 0 and 1 of the variable descriptor represent the HEX value 
of the two characters assigned to that particular variable. If there 
is only one character assigned to the variable, Byte 1 will contain 
the HEX value $00. 

2) If the variable is an Integer (%), the values stored in Bytes 0 and 
1 of the variable descriptor represent the HEX value of the two 
characters assigned to that particular variable, but, with bit seven 
set in both of the characters. If there is only one character 
assigned to the variable, Byte 1 will contain the HEX value $80. 

3) If the variable is a String ($), the values stored in Bytes 0 and 1 
of the variable descriptor represent the HEX value of the two 
characters assigned to that particular variable. However, this 
time, bit seven is set only in the second character which is stored 
in Byte 1. If the variable name only contains one character, Byte 
1 of the variable descriptor will contain the HEX value $80. 

4) If the variable is a Function variable (FN), the values stored in 
Bytes 0 and 1 of the variable descriptor represent the HEX value 
of the two characters assigned to that particular variable. 
However, bit seven is set only in the first character which is 
stored in Byte 0. If there is only one character assigned to the 
variable, Byte 1 will contain the HEX value $00. 

To further clarify this point, let's see what each type of variable name looks 
like in memory. The following figure illustrates how each type of variable is 
represented by setting bit seven in one, both, or neither of the characters in 
the variable name. 



18 




Abacus Software 



C-128 BASIC 7.0 Internals 



VARIABLE 

NAME 


BYTE 
00, 01 


VARIABLE 

TYPE 


AA 


41,41 


Floating Point 


AA% 


Cl, Cl 


Integer 


AA$ 


41, Cl 


String 


DEF FN AA (XX) 


Cl, 41 


Function variable 



Now that we have discussed how each variable type is identified in the 
variable name, let's cover how these different types appear in memory for 
the three categories of variables: Simple, Complex, and Function variables. 



1.3.1 Simple Variables 



Simple variables are non-array variables. This category of variables can be 
broken down into three types: Floating Point, Integer, and String variables. 
We will take each type and show how each appears in memory and describe 
the meaning of each byte that is associated with that type of variable. 

First, type in and run the following short program, it will make it easier to 
see how actual values are stored using each type. 

10 AA = 1.7 

20 AA% = -117 
30 AA$ = ,, C-128" 

The table below shows a memory dump of the area where those variables 
are stored. Remember, variable storage starts in RAM BANK 1 at $0400. 



ADDRESS: BYTE 

IN HEX : 00: 01: 02: 03: 04:05: 06: 


VARIABLE TYPE 


BASIC STATEMENT 


>10400 :41:41:81:59:99:99:9A: 
>10407 :C1:C1:FF:8B:00:00:00: 
>1040E :41:C1:05:F9:FE:00:00: 


Floating Point 

Integer 

String 


AA =1.7 

AA% =-117 

AA$ ="C-128" 
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1.3.1.1 Floating Point Variables 



Floating Point variables (FP) are used when a high degree of accuracy is 
needed in mathematical calculations. This is because a FP value can range 
from 2.93873588 E - 39 to 1.70141 183 E + 38. 

The C-128 calculates the FP value to 10 digits of precision which requires 5 
bytes of storage area as seen in the table below. For an example of how a 
FP variable is stored in memory, type the following in DIRECT mode and 
press <RETURN>: 



CLR: A = 128 

Now, enter the MONITOR and type M 10400 10407 and press 

<RETURN>. This will display the memory in RAM BANK 1 from $0400 
to $0407 which contains the descriptor of the variable A as shown below. 

>10400: 41 00 88 00 00 00 00 

Since this type of variable is a Floating Point variable, bit 7 is not set in 
either of the two characters of the variable name stored in bytes 0 and 1. 

The description of the seven bytes that make up the Floating Point Variable 
Descriptor is shown below. 



F] 


LiOATING POINT VARIABLE DESCRIPTOR 


BYTE 00 
01 
02 

03 

04 

05 

06 


Variable name with bit seven not set 
Variable name with bit seven not set 
Exponent value (EXP) 

Ml 

M2 

M3 

M4 



The way the C-128 represents a FP value at first seems to be complicated 
but in reality, it is not. For example, to convert the Integer value 53 to its 
binary FP equivalent, the following steps must be followed : 
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1 . Calculate the highest power of 2 that will divide evenly into the 
specified value. The closest power of two that will divide into 
the value 53 is 5. After dividing the value of 53 by 2 to the fifth 
power, this leaves a remainder of 21 ($15). 

53 = 2^ with a remainder of 21 ($15) 

2. Derive the exponent by adding 129 ($81) to power of two that 
was calculated in the step 1. 

5 + 129 = 134 ($86) 

3. Convert the remainder from the operation in step 1 to binary 
format. 

21 = 00010101 = (2 4 + 2 2 + 2°) = (16 + 4 + 1) 

4. Take the highest power of 2 that was obtained in step 1 (which 

is 5 in this example) and subtract one from it which will give 
you 2 4 . Then, starting with bit 6 of Ml. write 24, etc until you 
reach bit 0 of M4 which would have 2" . 

Then take the binary representation of 21 and starting from bit 
6 in Ml (Bit 7 is the sign bit) moving toward bit 0, locate the 
first bit that is set, which in this example would be bit 4. This 
bit represents 2 4 , so place that T into BIT 6 of M4. Then 
place the remaining bits, regardless if they are set or cleared, 
into the remaining bits in Ml until you place the last bit of the 
binary value for 21, which is a one in this case, into bit 2 of 
Ml. Then fill the remaining bits in Ml with zeros along with 
M2 - M4. Finally , since the original value was positive, place a 
zero for BIT 7 in Ml. If the value would have been negative 
you would have set BIT 7 to indicate this. After you have 
completed the representation of Ml thru M4, they should look 
like the figure on the next page. 
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1 0 0 0 0 1 1 0 

7 6 5 4 3 2 1 0 

Exponent 



0 1 


0 1 


010001010100 


0 10 10 10 0 


0 10 10 10 0 


Binary 


4 


3 2 


1 0 - 1-2 -3 -4 -5 -S -7 -8 -9 -10 


- 11 - 12 - 13 - 14 - 15 - 16 - 17-18 


- 19 - 20 - 21 - 22 - 23 - 24 - 25-26 


Representation 




, 9 


9999 99999999 


22222222 


22222222 


Bit value 


7 6 


5 4 


3210 76543210 


7 6 5 4 3 2 1 0 


7 6 5 4 3 2 1 0 






Ml 


M2 


M3 


M4 


Mantissa 



Floating Point representation of the value 53 



Exp = $86 
Ml = $54 
M2 = $00 
M3 = $00 
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1.3.1.2 Integer Variables 



As you can see in the table below, an Integer variable's value is stored in 
MSB, LSB format respectively. An Integer value can range from -32768 to 
32767. In HEX, these values are represented as $FFFF to $7FFF with 
$8000 to SFFFF representing -32768 to -1, and $0000 to $7FFF 
representing 0 to 32767. Integer variables should be used as often as 
possible to increase the execution speed of a program. 

For an example of how an Integer is stored in memory, type the following 
in the DIRECT mode and press <RETURN>: 

CLR : A% = 32767 

Now, enter the MONITOR and type M 10400 10407 and press 

<RETURN>. This will display the memory in RAM BANK 1 from $0400 
to $0407 which contains the descriptor of the variable A% as shown below. 

>10400: Cl 80 7F FF 00 00 00 

Since this type of variable is an Integer variable, bit 7 is set in both of the 
two characters of the variable name that are stored in Bytes 0 and 1. 

The description of the seven bytes that make up an Integer Variable 
Descriptor is shown below. 



INTEGER VARIABLE DESCRIPTOR 


BYTE 00 


Variable name with bit seven set 


01 


Variable name with bit seven set 


02 


MSB of the 16 bit binary value 


03 


LSB of the 16 bit binary value 


04 


not used filled with zero 


05 


not used filled with zero 


06 


not used filled with zero 
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1.3.1.3 String Variables 



String variables are not quite as difficult to handle or understand as Floating 
Point Numbers but require more effort to manage than Integer variables. 
The creation of a string variable by the operating system is fairly straight- 
forward. With the exception of the system's reserved strings such as DS$, 
the main entry point for the creation of a string is usually through the 
BASIC LET command at $53C6. There are many routines that are required 
to manage string variables such as the routines that add and delete the string 
from memory by either adding it to the bottom of the string storage area or 
moving the strings that are below it up over the one to be deleted. The actual 
storage format for the string variable itself is very simple. 

For an example on String variable storage, let's create a string in memory 
by using the normal BASIC method. Type in the following statement and 
press <RETURN>: 



CLR:A$= n C-128" 



Now let's see what happened. When the CLR command was executed, it 
reset the system pointers back to their normal values. This simply told the 
operating system to start placing the variable descriptors at $0400 moving 
upward towards $FF00 and to start placing the actual strings at $FF00 
moving downward towards $0400. 

Now enter the monitor by typing MONITOR in the DIRECT mode and 
pressing <RETURN>. Enter M 10400 10407 and press <RETURN > to 
inform the monitor that you wish to see a HEX dump of the memory from 
$0400 to $0407 in RAM BANK 1. This area of memory is where the 
variable descriptors are stored. If you look at the first seven bytes which are 
the variable descriptor for A$, you will see the following: 

>10400 : 41 80 05 F9 FE 00 00 

Now if you start with the first byte of the descriptor (nominal byte zero) 
which is at $0400, you will find a HEX value of $41. This is the first 
character of the variable name which is the letter A. The second character of 
the variable name, stored in Byte 1, was not specified. Therefore, the 
operating system set bit seven in the second byte of the descriptor in order 
to indicate that this descriptor is for a string. 
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The description of the seven bytes that make up a String Variable Descriptor 
is shown below. 



STRING DESCRIPTOR 


BYTE 00 


Variable name with bit seven not set 


01 


Variable name with bit seven set 


02 


Length of the string 


03 


LSB of the address of the string in RAM BANK 1 


04 


MSB of the address of the string in RAM BANK 1 


05 


not used filled with zero 


06 


not used filled with zero 



The following table indicates how the string that was assigned to A$ above 
would be stored in RAM. 



STRING STORED IN RAM BANK 1 


ADDRESS FEF 9 


C 


FEFA 


- 


FEFB 


1 


FEFC 


2 


FEFD 


8 


FEFE 


02 : LSB, MSB of the 


FEFF 


04 : address of this 




string's descriptor 



Remember that strings are added one character at a time moving downward 
toward $0400. The two bytes that preceed the string ($FEFE and $FEFF) 
are the address which points to the length of the string in the variable 
descriptor. The reason for this address is to enable garbage collection to 
scan through the string storage area and locate which strings are no longer 
required. 'Hie flag for the garbage collection is very simple. When a string is 
to be discarded, a routine will place an $FF in the MSB of the descriptor's 
address after the string and place the length of the string in the LSB of the 
descriptor's address. For example, in DIRECT mode type the following 
statement and press <RETURN>. 

CLR: A$ = "COMMODORE" :B$ = "64":C$ = "128":B$="" 
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The operating system first performed a CLR. Then it assigned the string 
variables and placed the strings in the string storage area. When it reached 
the statement B$="", it placed the new string (" ") at the bottom of the 
string storage area and changed the address of the variable descriptor after 
the B$=” 64 " to $FF02, in LSB, MSB format. Go into the MONITOR and 
enter J F92EA which forces a garbage collection. Now look at what 
happened to your strings. You now know how garbage collection is 
performed and why, if you have a lot of strings and you delete the first 
string that was created, your computer seems to hang up on you! 



1.3.2 Complex Variables 



A Complex variable is another name for an Array variable. This category 
can be broken down into three types: Floating Point , Integer, and String 
variables. We will take each type and show how each appears in memory 
and then describe the meaning of each byte that is associated with that type 
of variable. 

The first thing that should be noted is that the three types of complex 
variables are identified by setting Bit 7 in one, both, or neither of the 
characters in the variable name that is assigned to die array. This is the same 
method of identification that is use with the simple variable types. 

The following figure illustrates how the name of each type of complex 
variable is represented in memory. 



VARIABLE 

NAME 


BYTE 

00,01 


VARIABLE 

TYPE 


AA (0) 
AA% (0) 
AA$ (0) 


41, 41 
Cl, Cl 
41, Cl 


Floating Point 

Integer 

String 



To better understand how the different variable types are stored in memory, 
type in and RUN the following BASIC program: 
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10 DIM AA (0 ) , AA%(0), AA$(0) 

20 AA (0) = 1.7 

30 AA% (0) = -117 
40 AA$ (0) = "C-128” 

The following figure represents what a memory dump of the area where the 
variables are stored would look like: 



ADDRESS: BYTE 

IN HEX :00:01:02:03:04:05:06:07:00:01:02:03 VARIABLE TYPE STATEMENT 


>10400 :41:41:0C:00:01: 00:01: 81:59:99: 99: 9A: 
>1040C :C1:C1 :09:00 :01: 00 :01:FF:8B:41:C1 :0A: 
>10418 :00 : 01 :00 : 01 :05:F9:FE: 


Floating Point 

Integer 

String 


AA (0) - 1.7 

AA% (0) —117 
AA$ (0) -"C-128 



1.3.2.1 The Array Descriptor 



The array descriptor is basically the same for all three types of complex 
variables. The first two bytes contain the variable name and the 
aforementioned flags set in the name to indicate the variable type. The next 
five bytes describe the array size and how many dimensions and how many 
elements that are in the array. The array descriptor is only used once for 
each different array that is defined. For example, if you define an array of 
ten elements, the descriptor is used once followed by a list of the elements. 

The table below describes each of the bytes that can be found in an array 
descriptor: 
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ARRAY DESCRIPTOR 


BYTE 00 


Variable name with the flags set in 


01 


The same manner as simple variables 


02 


This byte contains the number of bytes in the ARRAY 
descriptor (7) + (the number of bytes which make up 


03 


the ARRAY ELEMENT * the number of elements 
which is stored in LSB, MSB format 


04 


The number of dimensions in the array 


05 


The number of elements in the array which was 


06 


specified in the DIM statement +1 because the 
A$ (0) is a valid element 



When an ARRAY descriptor is created it is formed in a totally different 
manner then the SIMPLE descriptors. Let's take each one of the bytes in the 
descriptor and spend a little time with them. Enter the following BASIC 
program so that you will be able to follow along with us. 

10 DIM A % (1,2, 3,4, 5) 

20 DIM B $ (10,10) 

30 A % (0,0, 0,0,0) = 1 

40 B $ (0,0) = "BASIC 7.0 INTERNALS" 

RUN the aforementioned program then do a MEMORY dump of 10400 thru 
10410 and 109 AF 109BF which should look like this. 

NOMINAL BYTE 





00 01 


02 03 04 


05 06 07 08 


09 OA 


0B 0C 


0D 0E 


OF 10 


>10400 


:C1 : 80 


: AF : 05 :05 


: 00 : 06 :00:05 

FIRST ELEMENT 
: 00 : 0B : 00 : 0B 


: 00 : 04 


: 00 : 03 


: 00 : 02 


: 00 : 01 
A 


>109AF 


: 42 : 80 


: 74 : 01 :02 


: 13 : EB 

A 


: FE : 00 

A 


: 00 : 00 


: 00 : 00 



FIRST ELEMENT 



SECOND ELEMENT 
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Bytes 0 through 1 are used in the same manner as SIMPLE variables. 

Bytes 2 through 3 are used to inform the operating system of two things. 
First of all, they are used to find the address of the next ARRAY descriptor. 
In our example these bytes contain AF 05 which, when added to the current 
descriptor's address ($0400), would give us the address of the next 
ARRAY descriptor, which is $09 AF. This is also used by the operating 
system as the address of the last ARRAY'S element. This value is obtained 
by the following formula: 

ADDRESS = 7+ (2* (ND- 1))+(VAR * (EL1+1*EL2 +1...)) 

Where: 

ND = The number of dimensions - 1 (5,5 would be 2 dimensions) 
el = The element value of the array (5,5 - ELI = 5 , EL2 = 5) 
var = Number of bytes per variable type : 

Integers = 2 

Strings = 3 

Floatingpoint = 5 



Using this formula , bytes 2 and 3 of our first array would be calculated as 
follows : 

7 + (2*4) + (2*(2*3*4*5*6)) 

15 + (2 * 720) 

1455 

When 1455 is converted to hex format the result is $05AF which is stored 
in byte 2 and 3 as AF:05. 

Byte 4 is used to indicate the number of DIMENSIONS in the ARRAY, this 
byte is used in conjunction with byte $05 thru NN and in our first example 
this value is 5 which indicates the number of DIMENSIONS that are used in 
this array. 

Byte 5 thru NN (0A) is used to indicate the number of elements in each 
dimension, in the statement DIMA%(10,10) these two bytes would contain 
$00,$0B in LSB/MSB format, followed by $00,$0B, followed by byte 9 
which is the first element in the ARRAY which is (0,0,0). 
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As stated before, the main difference between the different types of arrays is 
in the way that the elements of each type are stored. We will take each type, 
describe each byte of the element, and then show what an array of that 
particular type would look like in memory. 



1.3.2.2 Floating Point Arrays 



The Floating Point array is used to stored numbers with 10 digit accuracy. 

The array consists of the array descriptor followed by a list of the values of 
the five byte Floating Point numbers that were assigned to the array. 

For example, type in the following statement and press <RETURN>. 

CLR:DIM A(0) :A(0) = 328.67 

The following table illustrates how this type of array would appear in 
memory if you were to do a M 10400 10 4 0C from the MONITOR. 

>10400 : 41 00 0C 00 01 00 01 89 24 55 C2 8F 

The following table describes the meaning of the individual bytes that 
follow the array descriptor. The first Floating Point element begins at 
location $10408. 



FLOATING POINT NUMBER ELEMENT 


BYTE 00 


Exponent value 


01 


Ml 


02 


M2 


03 


M3 


04 


M4 



If there was more than one element assigned to the array, the same sequence 
of bytes for each Floating Point Number element would be listed following 
the descriptor. 
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1.3.2.3 Integer Arrays 



The Integer array is used to store numbers that do not require the degree of 
accuracy that the Floating Point Number array has to offer. The format in 
which the Integer array is stored is the same as the Floating Point array 
except, the Integer array only requires two bytes for each element. 

For example, type in the following statement and press <RETURN>. 

CLR-.DIM A% ( 0 ) : A% ( 0 ) = 1296 

The following line illustrates how this type of array would appear in 
memory if you were todoaM 10400 10409 from the MONITOR. 

>10400 sCl 80 09 00 01 00 01 05 10 

The following table describes the meaning of the individual bytes that 
follow the array descriptor. The first Integer element begins at location 
$ 10407 . 



INTEGER ARRAY ELEMENT 
BYTE 00 MSB of the 16 bit binary value 

01 LSB of the 16 bit binary value 



If there were more than one element assigned to the array, the same 
sequence of bytes for each Integer element would be listed following the 
array descriptor. 



1.3.2.4 String Arrays 



The String array is used to store strings of characters and not numerical 
values like the Floating Point and Integer arrays do. With a String array, the 
list of String elements that follow the array descriptor are the lengths and 
addresses of the strings that are stored in the String Storage Area. 
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For example, type in the following statement and press <RETURN>. 
CLR-.DIM A$ (0) :A$ (0) = ,, C-128" 

The following table illustrates how this type of array would appear in 
memory if you were todoaM 10400 1040A from the MON I TOR. 



>10400 : 41 80 0A 00 01 00 01 05 F9 FE 

The following table describes the meaning of the individual bytes that 
follow the array descriptor. The first String element begins at $10408. 



STRING ARRAY ELEMENT 


BYTE 00 


Length of the string 


01 


LSB of the address of the string in RAM BANK 1 


02 


MSB of the address of the string in RAM BANK 1 



1.3.3 Function Variables 



The last category of variables is the FuNction (FN) variables. This type of 
variable can only be defined using the Floating Point format. The main use 
of this variable is to allow the user to assign a formula or value to be used 
later when doing mathematical calculations. For instance, type in the 
following line and RUN it. 

10 DEF FN AA (AA) = 123 

The following figure would represent the way that a memory dump of the 
area where this variable is stored would look like. Remember, variable 
storage starts in RAM BANK 1 at $0400. 

>10400 :C1 41 11 1C 09 04 31 41 41 
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As you can see by the values of the variable name, the Function variable is 
identified by setting Bit 7 in the first character of the variable name. The 
following table gives a description of each of the bytes that are used to store 
this type of variable. 



USER DEFINED FUNCTION 


BYTE 00 


Variable name with bit seven set 


01 


Variable name with bit seven not set 


02 


LSB of the address of the expression in RAM BANK 0 


03 


MSB of the address of the expression in RAM BANK 0 


04 


LSB of the address of the variable descriptor in RAM BANK 1 


05 


MSB of the address of the variable descriptor in RAM BANK 1 


06 


Contains the first character of the expression 



1.3.4 Variable Pointers 



To make the storing of the different variable types possible, several pointers 
are used to keep track of where everything is. The following table and 
diagram will give you the different pointers that are used when storing 
variables in RAM BANK 1. 



LABEL 


LOCATION 


USE 


VARTAB 


$2F, $30 


This location holds the starting address of 
the variable descriptor storage area. It is 
normally set to $0400. 


ARYTAB 


$31, $32 


This location holds the starting address of 
the array storage area. 


STREND 


$33, $34 


This location holds the address of the end of 
the BASIC arrays plus one. 


FRETOP 


$35, $36 


This location holds the address of the bottom 
of the string storage area. 


MAXMEM1 


$39, $40 


This location holds the address of the the 
top of the string storage area. It is always 
set to $FF0 0 . 
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When the 128 is first turned on, vartab is set to point to the start of the 
BASIC variable storage area in RAM BANK 1 and MAXMEM1 is set to the 
end of the BASIC variable storage area in RAM BANK 1. Normally, 
VARTAB is set to point to $0400 and maxmemi is set to point to $FF00. 

| 1 MAX 

Memor y 1 

String 
Storage Area 

FRETOP 

Currently unused 
memory space that 
is reserved for 
string storage 
and/or ARRAY storage 
See Text for more 
details 

STREND 

ARRAY storage area 

ARYTAB 

Variable 
descriptor 
storage area 

0 4 0 0 VARTAB 

Common user 
area 

Available to 
all banks 

0000 - 



When the BASIC CLR routine is called during system initialization, the 
address that is stored in vartab is stored in ARYTAB and STREND and the 
address that is stored in maxmemi is stored into FRETOP. This resets all of 
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the pointers to their starting addresses to indicate to the operating system 
that there are not any variables in the variable storage area. 

However, if in the DIRECT mode we were to define a Floating Point 
variable, arytab and strend would be incremented by seven in order to 
make room for the descriptor of the variable that was being defined. These 
pointers would then point to the next available location for the next variable 
descriptor or for an array. 

If we then define a Floating Point array, ARYTAB would stay where it is, 
but STREND would be be incremented the number of bytes that the array 
needs to make room for that array. So far, we have defined a Floating Point 
variable and a Floating Point array. Now let's try something different. Let's 
define a String variable and see what happens. 

If we define a String variable, arytab and STREND will be incremented 
by seven to make room for the String variable's descriptor. However, this 
time FRETOP will be decremented the number of bytes needed for the actual 
string, plus two. The two extra bytes of memory are used to hold the 
address that points to the length of the string in the variable's descriptor. 
Consequently, anytime you define a string, not only are ARYTAB and 
STREND moved but, FRETOP as well. Let's go one step further and define 
a String array. 

When you define a String array, ARYTAB remains where it is and STREND 
is incremented the number of bytes that are needed for the new array. Also, 
FRETOP is decremented the number of bytes needed for the string part of 
the array plus two. Once again, the two extra bytes of memory are used to 
hold the address that points to the length of the string in the variable's 
descriptor. 

As you can see from the examples above, arytab, strend, and fretop 
change with each variable that is defined. The pointers are incremented or 
decremented as necessary when a variable is added or deleted. 

If in the process of adding a new variable, the pointers STREND and 
FRETOP collide, an 'OUT OF MEMORY' error message is generated. 
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1.3.5 A Variable Dump Program 



As we have seen, there are several types of variables, and each variable type 
has its own format when stored in memory. It would therefore be quite 
useful if a routine was designed to display the value of the variables that are 
stored in memory. Many times it becomes necessary when writing a BASIC 
program to see what the variable values are so that an assessment can be 
made as to whether the program that is being written is operating as it 
should. Without a program such as the variable dump program that is 
presented here, it would become quite tedious to print all of the variable 
values to the screen one at a time. However, VARIABLE DUMP makes the 
job of displaying the individual variable values easier by providing a two 
character command in order to initiate a dump to the screen of all of the 
variable values that are stored in memory. The only variable type that is not 
handled by the variable dump program is arrays. This is due to the 
large number of elements that are present in arrays. However, with a little 
effort on your part, this function could be added to the present variable 
dump program. 



1.3.5.1 How To Use The variable dump Program 

In order to use the variable DUMP program, type in the BASIC 
generator program listed in the section below. This program when RUN will 
POKE the data to memory that is necessary to construct the VARIABLE 
DUMP machine code. After you have typed in the BASIC generator 
program, save a copy of the program to disk. This will ensure that you will 
still have a copy of the program should the computer crash or an error in 
typing was made. This is a good practice to get into, especially with lengthy 
programs, or programs that contain a large amount of DATA statements. 

Once the program has been saved to disk, type RUN and press <RETURN>. 
The program will indicate that it is running by displaying the message 
CURRENT DATA line followed by the line number of the DATA 
statement that is currently being put into memory. If an error in the DATA 
statements should be encountered, an ERROR IN data-line message 
will be displayed followed by the line number of the DATA statement where 
the error lies. 
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Once the generator program has finished placing the variable dump machine 
code into memory, you will be prompted DO YOU WISH TO SAVE AN 
OBJECT FILE ( Y/N ) . If you want an object file to be saved to disk type 
<Y>. After the object file has been saved to disk by the BASIC generator 
program, you will be prompted once again DO YOU WISH TO SAVE AN 
OBJECT FILE. This feature was included in the program so that a copy of 
the variable dump program's object file could be saved to as many disks as 
desired without having to rerun the original BASIC generator program each 
time you wanted to save a copy of the object file to another disk. It is 
recommended that you save a copy of the variable dump program's object 
file to each disk that you use for the development of BASIC programs as 
you will soon find out that the function that this program serves will be used 
over and over again when developing a BASIC program. 

Once you have finished saving a copy of the object file to the disks you 
want it on, type <N> in response to the prompt DO YOU WISH TO SAVE 
AN OBJECT FILE. After you have done this, the message TYPE SYS 
3072 TO activate will be displayed on the screen and the generator 
program will end. The SYS address that is displayed is the address that will 
initialize the VARIABLE DUMP program. Therefore, type <SYS 3072> and 
press <RETURN>. 

Once the program has been initialized, the READY prompt will appear on the 
screen. To use the new added function, type <@V> and press 
<RETURN>. Immediately, the program will print the values of all of the 
variables that are presently stored in memory except the array variables. In 
order to print the variable dump to the printer, enter the following BASIC 
statement in the DIRECT mode: 

OPEN 4,4,7: CMD4 : @V 

Once the VARIABLE DUMP program's object file has been saved to a disk, 
the next time that you wish to use the program, type the following: 

1541 Disk Drive: BLOAD "VARIABLE DUMP .0",B15 : SYS 3072 

or 

1571 Disk Drive: BOOT "VARIABLE DUMP.O",B15 
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1.3.5.2 The Variable Dump Generator Program 



The following BASIC program is designed to generate the VARIABLE 
DUMP program as well as allow you to save the object file to disk. 

10 GOTO140 

20 : 

30 : VARIABLE DUMP GENERATOR 
40 : 

50 : COPYRIGHT (C) 1986 BY 
60 : 

70 : JIM D. SPRINGER 

80 : 

90 : AND 

100 : 

110 : DENNIS J. JARVIS 

120 : 

130 : 

140 SCNCLR 

150 Y=0 : LN=250 :AD=DEC ("0C00”) 

160 FORI=ADTOAD+310STEP8:Y=XOR(Y, 15) : 

VOLY: PRINT" [HOME] CURRENT DATA LINE "LN 
170 READD$ : POKEI+X, DEC (D$) 

180 X=X+1 : CK=CK+DEC (D $ ) : IFXO8THENG0T0170 
190 READCK$ : IF (CK AND 255) ODEC (CK$) THENPRINT "ERROR 
IN DATA - LINE "LN: END 
200 X=0:CK=0:LN=LN+10:NEXT 

210 PRINT" [CURDN] [CURDN]DO YOU WISH TO SAVE AN 
OBJECT FILE (Y/N) " 

220 GETKEYA$ : IFA$<>"Y"AND A$O"N"THEN220 
230 IFA$="Y"THEN SCRATCH "VARIABLE DUMP.O" : 

BSAVE "VARIABLE DUMP . O" , B0, P (AD) TO P(I): 
VERIFY"*", 8: ELSE PRINT" [DOWN] TYPE SYS"AD 
" TO ACTIVATE" :END 
240 GOTO210 

250 DATA A0,0C,A9,10,A2,4C,8E,8D, 6E 
260 DATA 03, 8D, 8E, 03, 8C, 8F, 03, 60, 9F 
270 DATA 8D, 03, FF, 48, C9, 40, DO, 12, C2 
280 DATA A0, 01,20, C9, 03, C9, 56, DO, 7C 
290 DATA 09,C8,20,C9,03,F0,07,4C, 00 
300 DATA 6C, 79, 68, 4C, 90, 03,20,F0, 3C 
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310 DATA 84, 68, A9, 00, 8D, 00, FF, 8D, AE 
320 DATA 04,D5,A5,2F,A4,30,85,FB, 01 
330 DATA 84, FC, C4,32,D0,02,C5,31, 3E 
340 DATA 90, 09, 20, 7 A, 41,4C,37,4D, 44 
350 DATA 4C, 0C, 40, A9, 0D, 20, D2, FF, 3F 
360 DATA AO, 00,84, 0F,20,2F, OD, AA, 39 
370 DATA 29, 80, 4A, 20, 1A, OD, 20, 2F, 89 
380 DATA OD, AA, 29,80,20, 1A, OD, A5, 4C 
390 DATA OF, FO, 2 A, C9,80,F0,36,C9, 61 
400 DATA 40,F0,52,20,D5,0C,20,F5, 98 
410 DATA OC, AO, 00,20, 2 A, OD, A8, 8 A, 35 
420 DATA 20, 3C, 79, 20, 42, 8E, AO, 00, 65 
430 DATA B9,00,01,F0,06,20,D2, FF, A1 
440 DATA C8,D0,F5,F0, 64, 20, DB, OC, E8 
450 DATA 20, F5, OC, A5,FB,A4,FC, 20, 81 
460 DATA 85, 7A, 4C, 8B, OC, 20, F5, OC, 03 
470 DATA 20, D8, OC, 20, FO, 0C,A0, 00, CO 
480 DATA 20, 2 A, 0D,F0,0B,85,24,C8, C3 
490 DATA 20,2F,0D,85,25,20,E9,55, 64 
500 DATA 20,F0,0C,D0,34,20,DB,0C, 27 
510 DATA 20, ED, OC, DO, 2F, A9, 25, 2C, 12 
520 DATA A9, 24 , 2C, A9, 20,20,D2, FF, B3 
530 DATA A9, 20,20, D2, FF, A9, 3D, 20, CO 
540 DATA D2,FF,A9,20,2C,A9,2A, 2C, C5 
550 DATA A9, 22, 4C,D2,FF, A5,FB, 18, AO 
560 DATA 69, 02, 85, FB, 90, 02,E6,FC, 5F 
570 DATA 60,A9,05,2C,A9,07, 18,85, 87 
580 DATA OD, A5,FB, 65, OD, 85, FB, 90, 2F 
590 DATA 02 , E6, FC, A5, FB, A4, FC, 4C, 70 
600 DATA 42, OC, 05, OF, 85, OF, 8A, 29, A9 
610 DATA 7F,D0,02,A9,20,20,D2,FF, OB 
620 DATA C8, 60,20, 2F,0D,AA,C8,A9, 9F 
630 DATA FB, 20, AB, 03, 60, FF, C8, 60, 50 



NOTE: The BASIC generator program above (as well as the MERLIN 
source file of the variable dump program) is included with the other 
programs appearing in this book on the optional disk available from Abacus 
Software. See the back of this book for order information. 
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1.4 Memory Expansion for the C-128 



There are two main types of memory devices used in the 128 to store data, 
programs, and the routines that allow the 128 to operate. These two types of 
memory devices are RAM (Random Access Memory) and ROM (Read Only 
Memory). 

RAM is a storage device that can be both written to and read from. 
However, when power is removed from a RAM chip, all the data that was 
stored is lost. This is one of the biggest disadvantages of this type of 
storage device. Therefore, RAM is intended for the temporary storage of 
data. 

One of the advantages of RAM is that it is faster than many other types of 
storage devices such as a disk drive or cassette drive. In the 128, RAM 
chips are used for the 128K of memory space, for the screen storage area 
for the VDC, and for the screen storage area for the VIC. 

ROM is a storage device that usually can only be read. The function of a 
ROM is to supply a permanent storage area for data. This data cannot be 
erased by merely turning off the power switch. 

In the 128, there are several ROMS: Character ROM, BASIC ROM Low, 
BASIC ROM High, and the KERNAL ROM. Each one contains data that is 
necessary to enable the 128 to accomplish all of the functions that it was 
programmed for. 

In the following text we will discuss both the RAM and ROM expansion 
methods in the C-128. 
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1.4.1 RAM Expansion 



There are two other ways in which RAM is used with the 128 that are 
particularly interesting. In fact, they allow the user to be able to expand the 
memory capabilities of the 128. The two ways to expand the memory 
capability of the 128 are adding RAM for BANKS 2 and 3 and the RAM 
Expansion Module (REM). 

Although the software exists to support the addition of RAM for BANKS 2 
and 3, the 128's motherboard does not provide the hardware necessary to 
implement these RAM BANKS. When the 128 was produced, the memory 
addressing scheme was never completed for this type of RAM expansion. 
Unless someone comes out with an internal modification to the 
motherboard, the 128 will never have any more than 128K of internal 
contiguous RAM. 

However, the second method of expanding the 128's RAM is a little more 
usable. This method involves plugging a REM into the expansion port to 
increase the 128's memory capacity. The two RAM modules currently on 
the market are the 1700 and 1750 expansion modules that let you expand the 
128's memory by 128K and 512K bytes, respectively. The RAM that is 
added cannot be accessed in the same manner as RAM inside the 128 .The 
module acts more like a RAM disk and is accessed by using the BASIC 
commands FETCH, STASH, and SWAP. 



1.4.1.1 The RAM Expansion Unit's Controller 



The process that makes all of this possible is known as Direct Memory 
Access, whereby an external controller is allowed to take over the 
computer's bus system to affect the data transfer from the external memory 
to the computer's memory (FETCH), from the computer's memory to the 
external memory (STASH), or exchanging the computer memory with the 
external memory (SWAP). 

The RAM Expansion Controller (REC) used in the 1700 and 1750 RAM 
expansion modules is the 8726. It is responsible for handling all the 
operations that are necessary for transferring data between the expansion 
module and the 128. 
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The 8726 has 1 1 registers that are used to control the DMA process. These 
registers appear in locations $DF00 to $DF0A. 

The following table gives the various registers and the description of each 
that is used to control the DMA process. 



Address 


Label 


Label description 


$DF 0 0 


DMAS T 


DMA status 


$DF0 1 


DMACMD 


DMA command 


$DF 0 2 


DMAADL 


DMA Address Low 


$DF0 3 


DMAADH 


DMA Address High 


$DF 0 4 


DMALO 


DMA LOw 


$DF0 5 


DMAHI 


DMA High 


$ DF 0 6 


DMABNK 


DMA BaNK 


$DF 0 7 


DMADAL 


DMA Data Address Low 


$ DF 0 8 


DMADAH 


DMA Data Address High 


$ DF 0 9 


DMAIMR 


DMA Interrupt Mask Register 


$DF 0 A 


DMAST 


DMA Address Control Register 
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1.4.1.1.1 DMA STatus register (DMAST) 



The DMA STatus register for the REC is located at $DF00. This is a read 
only register that is used to store the status of the REC. The definition of 
each bit of this register is as follows: 



BIT 7 This bit is used to indicate whether there is an interrupt pending. 

If this bit is set, this indicates that there is an interrupt waiting to 
be serviced. Note: If Bit 7 is set in the DMAIMR (see Section 
1.4. 1.1.7), then whenever Bit 6 or 5 of this register is set, then 
a hardware IRQ is generated, and must be handled by the 
KERNAL IRQ vector at $0314/$0315. 

BIT 6 This bit is used to indicate whether the transfer of a block of data 
has been completed. If this bit is set, the block has been 
transferred (see $DF09). 

BIT 5 This bit when set indicates a verify error (see $DF09). 

BIT 4 This bit when set indicates that the RAM expansion is a 1750 

model (512K) and not the 1700 model (128K). 

BITS 3-0 Contain the version number of the RAM Expansion Controller. 



1.4.1. 1.2 DMA CoMmanD register (DMACMD) 



The DMA CoMmanD register for the REC is located at $DF01. This register 
is used to store the command to the REC. The definition of each bit of this 
register is as follows: 

BIT 7 This bit when set can have two meanings. To execute the DMA 
process when location $FF0O is accessed again, or to execute 
the DMA process immediately depending on BIT 4 of this 
register. 

BIT 6 Not used at this time. 

BIT 5 This bit when set will activate the AUTOLOAD routine in the 
REC. This option, when activated, will preserve these registers: 
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DF02, DF03, DF04, DF05, DF07, DF08. This will enable you 
to perform the same DMA over and over again without having to 
set these addresses up every time you want to perform a DMA. 
The main purpose of the AUTOLOAD function is to save you 
memory. 

BIT 4 When set, this bit will execute the DMA immediately without 
having to store a value at $FF00. This bit defaults to 0 . 

BITS 3-2 Are not used at this time. NOTE: BASIC sets this bit each time a 
DMA is performed, it has no effect! 

BITS 1-0 These bits inform the REC of what type of DMA is to be 
performed and have the following meaning. 



BIT 1 0 


TYPE OF OPERATION 


0 0 


Transfer from C-128 to REM 


0 1 


Transfer from REM to C-128 


1 0 


Swap C-128 for REM 


1 1 


Verify C-128 with REM 



1.4.1.1.3 DMA ADdress Low/High register 
(DMAADL,DMAADH) 



The DMA ADDRESS LOW/HIGH registers are located at $DF02 and 
$DF03 respectively. These two registers are used to store the LSB and 
MSB of the starting address where die DMA process is to take place inside 
the C-128. 
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1.4.1. 1.4 DMA LOw/HIgh register (DMALO,DMAHI) 



The DMA LOW/HIGH registers are located at $DF04 and $DF05 
respectively. These two registers are used to store the LSB and MSB of the 
starting address where the DMA process is to take place inside the RAM 
Expansion Module . 



1.4.1. 1.5 DMA BaNK register (DMABNK) 



The DMA BANK register is located at $DF06. This register contains the 
BaNK number inside the RAM Expansion Module that the DMA is to take 
place in. The meaning of each of the bit values is shown below. 



BIT 2 


1 


0 


REM BANK 


APPLICABLE REM UNIT 


0 


0 


0 


0 


128K 


and 512K 


0 


0 


1 


1 


128K 


and 512K 


0 


1 


0 


2 


512K 


only 


0 


1 


1 


3 


512K 


only 


1 


0 


0 


4 


512K 


only 


1 


0 


1 


5 


512K 


only 


1 


1 


0 


6 


512K 


only 


1 


1 


1 


7 


512K 


only 
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1.4. 1.1. 6 The DMA data Address Low/High register 
(DMAAL,DMAAH) 



The DMA DATA ADDRESS LOW/HIGH registers are located at $DF07 
and $DF08 respectively. These registers are used to store the LSB and MSB 
of the number of bytes that the DMA is to process STASH, SWAP, etc. 



1.4.1.1.7 The DMA Interrupt Mask Register 
(DMAIMR) 



The DMA INTERRUPT register is located at $DF09 and is similar to the 
ICR register in a CIA. That is, you can select what type of situation or 
incident you wish to test for, and if this situation does occur, then BIT 7 in 
the DMA ST is set and the appropriate bit in that register is set to indicate 
which one of the following occurred. 

BIT 7 This bit is used to enable the interrupt flag. It is the 
responsibility of the software programmer to test the DAM 
STatus register which is located at $DF00, to see what has 
actually occurred, and process it accordingly. 

BIT 6 This bit, when set, indicates to the REC that you want it to set 
BIT 6 in location $DF00 when the End Of Block occurs. 

BIT 5 This bit, when set, indicates to the REC that you want it to set 
BIT 5 in location $DF00 when their is a verify error. 

BITS 4-0 Not used at this time. 
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1.4.1.1.8 The DMA Address Control Register 



The DMA ADDRESS CONTROL register is located at $DF0A. This 
register is used to inform the REC if it is to increment the addresses that are 
used for the DMA transfer. For instance, this register allows you to 
increment the address in the REM and not in the C-128 and vice versa. 



BIT 
0 1 


DESCRIPTION 


REGISTER AFFECTED 


1 


0 


Increment both addresses (DEFAULT) 


DMA ADL/ADH, DMA LO/HI 


U 


1 


Do not increment REM address 


DMA LO/HI 


H 


0 


Do not increment C-128 address 


DMA ADL/ADH 


1 


1 


Do not increment either address 





1.4.1.2 The Software Nuts and Bolts of DMA 



The process that makes the RAM expansion module possible is known as 
Direct Memory Access, whereby an external controller is allowed to take 
over the computer’s bus system to affect the data transfer from the external 
memory to the computer's memory, from the computer's memory to the 
external memory, or exchanging computer memory with external memory. 

The BASIC commands that are used with the RAM expansion module are 
the FETCH, STASH, and SWAP commands. The BASIC syntax for each is 
identical except for the command that is being used. The table below gives 
the syntax for these commands: 

Command syntax: 

FETCH, STASH, SWAP #bytes, insta, expsa, expb 



Where: tbytes = the number of bytes to be fetched, stashed, or swapped 
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insta = internal starting address (address in C-128) 
expsa = external starting address (address in REM) 
expb = external bank number (bank in REM) 

The FETCH command allows to transfer data from the RAM expansion 
module into the computer. When this command is used, the machine 
language routine at $AA28 is called to handle the execution of the 
command. 

For example, the statement FETCH 1024,1024,0,0 transfers IK of data 
from the RAM expansion module starting at $0000, ROM BANK 0, to the 
computer’s screen memory starting at location $0400. 

The STASH command allows you to transfer data from the computer's 
memory to the RAM expansion module. 

For example, the statement STASH 1024, 1024, 0, 0 transfers IK of 
data from the computer's screen memory starting at location $0400 to the 
RAM expansion module starting at location $0000 in BANK 0. 

The swap command allows you to exchange data between the computer’s 
memory and the RAM expansion module. 

For example, the statement SWAP 1024,1024,0,0 exchanges IK of 
data from the RAM expansion module starting at location $0000 in BANK 0 
to the computer's screen memory starting at location $0400 . 

The manner in which BASIC accomplishes the DMA is fairly straight- 
forward. It first converts the values that follow the BASIC statement and 
place them into the proper addresses to set up the REC (see the description 
of the REC registers above). Then it gets the current BANK number out of 
$03D5 which was placed there by the BASIC BANK command. After this 
has been completed, it calls the DMA CALL routine out of the KERNAL 
JUMP TABLE, which is located at $FF50. 

When the DMA CALL routine is called, the BASIC BANK number must be 
in the accumulator with the DMA command in the Y-register. When the 
DMA CALL routine is reached ($F7A5), it will take the BASIC BANK 
number and convert it over to the appropriate memory configuration value 
(for more information on memory configuration refer to the Appendices) 
with bit 0 omitted to keep the I/O register intact. Next, the routine will place 
this value into the Accumulator and the X-register and jump to the EDMA 
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routine at $03F0. This is the actual nuts and bolts of the DMA execution, so 
let's take a closer look at it. 



************************************* 



* * 

* EDMA * 

* * 

* Execute Direct Memory Access * 

* * 






$03F0: 


LDX 


$FF00 


$03F3: 


STY 


$DF01 


$03F6: 


STA 


$FF00 


$03F9: 


STX 


$FF00 


$03FC: 


RTS 





ADDRESS DESCRIPTION 



$03F0 Preserve the current memory configuration in the X-register 
$03F3 Place DMA command in the DMACMD register for the REC 

$03F6 Set the requested memory configuration, execute the DMA 

$03F9 Restore the old memory configuration 



As you can see, the previous routine is fairly straightforward. However, 
there is one thing to remember. The STA $FF00 is what actually executed 
the DMA process, because BASIC does not set BIT 4 in the DMACMD 
register for the REC. This instruction is why you cannot access any RAM 
BANK except RAM BANK 0. The REC in the RAM expansion module 
does not actually use the value that is in $FF00. It obtains its RAM 
information from the Memory Managment Unit Ram Configuration 
Register, or simply MMURCR. To help you past this shortcoming, we 
have reworked the Execute Direct Memory Access routine for you which 
will automatically extract the RAM BANK that you want to access and set 
the MMURCR for you. Then after the DMA process has been completed, 
the routine restores the MMURCR register back to its previous 
configuration value. 

The main entry point is still $03F0 to maintain compatibility with the 
existing operating system which is the top priority. 
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03E4 : 

03E7 : 
03E9: 
03EC: 
03EF : 



ORG $03E4 




/Spare memory area just 
/routine 


above 


EXECUTE = 


%00010000 


/Set the bit to DISABLE 
/ $FF00 TRIGGER 


the 


MMURCR 


$D506 


/Memory Management Unit 
/Configuration Reg. 


Ram 


DMAST 


$DF00 


/Direct Memory Access STatus 
/register 


DMACMD 


$DF01 


/DMA CoMmanD register 





★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★I* 
★ ★ 



SMMURCR 



Set MMU Ram Configuration Reg 



This routine will take the value that is in the * 
Accumulator which during a BASIC DMA is the memory * 
configuration of the current BASIC BANK number. * 



Bits 5 thru 0 are discarded because we are only 
concerned with the RAM BANK number that is 
requested. 



If your using this routine with machine language, 
just call EDMA with the RAM BANK number in the 
Accumulator (see the section on the MMU for more 
details) . 

ON ENTRY: A = Memory configuration 

X = Not used in this routine 

Y = Not used in this routine 

ON EXIT: A = New MMURCR value 

X - Old MMURCR value 

Y = DMACMD value 



★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★ 



AE 


06 


D5 


SMMURCR LDX 


MMURCR 


/Get the current RAM 
/Configuration register 


29 


CO 




AND 


#%11000000 


/Only use the RAM BANK 


0D 


06 


D5 


ORA 


MMURCR 


/ Configuration 


8D 


06 


D5 


STA 


MMURCR 


/Set VIC RAM BANK number 


60 






RTS 




/Exit the routine 
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I********************************************************* 



★ * 

* EDMA * 

★ * 

* Execute Direct Memory Access * 

★ * 



* This routine takes the memory configuration value * 

* that is in the Accumulator, sets Bit 4 in the value * 

* in preparation to execute the DMA process, and then * 

* stores the value in the DMA command register so that * 

* the DMA will be executed. * 

* ★ 



* ON ENTRY: A = Memory configuration 

* X = Unused 

* Y = DMACMD VALUE 



★ 

★ 

★ 

★ 



* ON EXIT: A = Status of the > DMA process 

* X = MMURCR configuration 







★ 


Y = DMACMD 


1 value 


★ 






★ 






★ 






********************************************************* 


03F0 : 


20 


E4 03 


JSR 


SMMURCR 


/Set the RAM BANK number 












/For the VIC memory 


03F3 : 


98 




TYA 




/Move the DMACMD into the 












/Accumulator 


03F4 : 


09 


10 


ORA 


♦EXECUTE 


/Set BIT 4 to Execute the 



;DMA process immediately 



★ — _____________________ ★ 

★ ★ 

* NOTE: The DMA process will occur on the next * 

* instruction. * 

* ★ 

★ * 



03F6 : 


8D 


01 


DF 


STA 


03F9 : 


8E 


06 


D5 


STX 


03FC : 


60 






RTS 



DMACMD ;Save the DMA command 

MMURCR /Restore the MMURCR to its 

/Previous memory config. 
/Exit EDMA 



The following BASIC program demonstrates the usefulness of the new 
EDMA routine. Type it in exactly as it is listed and save a copy to the disk. 
Note: Make sure that your RAM expansion module is plugged in before you 
try this demo program. 
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0 SCNCLR : REM FAST 
5 FORA=0TOl 

10 BANKA :FORI=DEC ( "2000" ) TODEC ("200A") : 

POKE I, A+48 : NEXT I, A: A$= "BEFORE " : GOSUB 1 0 0 
20 SLOW 

31 BYTES = 10 

32 C128 = DEC ("2000") 

33 REC = 0 

34 BNK = 0 

40 BANK0: STASH BYTES, C128, REC, BNK 
50 BANK1 : SWAP BYTES, (3128, REC, BNK 
60 BANK0: FETCH BYTES, C12 8, REC, BNK 
70 A$="AFTER":GOSUB140 
8- END 

100 PRINT: PRINT : PRINT "CURRENT CONTENTS ";A$;" DMA" 

101 FORA=0TOl -.PRINT: PRINT "RAM BANK"; A 
110 BANKA :FORI=DEC ("2000") TODEC ("200A") : 

PRINTCHR$ (PEEK (I) ) ; :NEXTI, A: RETURN 

Next, run the BASIC demo program to see that the data that was stored in 
RAM BANK 0 and RAM BANK 1 before and after the SWAP are the same. 
This will show you that normally BASIC will only enable you to use RAM 
BANK 0 for DMA. However, with this short and simple modification to the 
EDMA routine, DMA access to any RAM BANK is possible. 

Next, type in the new EDMA routine with the machine language MONITOR 
or an assembler and save a copy to disk. To demonstrate that the routine 
works, ensure that the new EDMA routine is in memory and rerun the 
BASIC demo program listed above. What you will see is that with the new 
EDMA routine, die data that was stored in RAM BANK 0 was indeed 
swapped with the data that was in RAM BANK 1. 
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1.4.1.3 Graphics Demo Program 



The following program will give you some idea of what you can do with the 
extra RAM in the RAM expansion module. The program first draws 16 
hi-res screens and saves then in the REM. The program will then FETCH 
the different screens one at a time to animate the figures on the screen. The 
16 screens use 128K of the RAM in the RAM expansion module. 

Type in the program as it is listed below and save a copy to disk. Next, run 
the program. It will take a couple of minutes to set up die screens. Feel free 
to play around with the graphics commands to generate different effects. 

1 GOSUB28:SCNCLR: PRINT V"K OF RAM IS INSTALLED" : SLEEP2 

2 SZ=1 6: FORH=0TO8 :N=INT (RND (1)*4)+1:X1(H) =N :NEXT 

3 GRAPHIC3 , 1 

4 FORJ=0TO8:X=X+15:X(J)=X:NEXT 

5 FOR J=0TO8 : Y ( J) =INT(RND(1) *20) +1:NEXT 

6 FORL=OTOSZ-1 : SCNCLR 

7 FORI=0TO8 : COLOR2 ,1 + 1 

8 FAST :Y1=180-(3*Y(I) ) 

9 CIRCLE2 , X ( I) ,180, 5, 5, ,,,90 :PAINT2, X(I) ,180 

10 CIRCLE2 , X (I) , Yl,5,5, , , , 90 :PAINT2 , X (I) ,Y1 

11 BOX2,X(I) -5, Y1,X(I) +5,180, , 1 

12 CIRCLE0, X (I) , Y1 , 5, 5, 90,270, , 90 

13 DRAW0, X (I ) , Yl+5 TO X (I) , 180+Y1-5 

14 NEXTI 

15 FORK=0TO8 : Y (K) =Y (K) +X1 (K) : IFY (K) <=1 OR Y (K) >=42THENX1 (K) =0 

16 NEXTK 

17 GOSUB32 

18 SLOW: STASH V,IA,AD,BN 

19 NEXTL 

20 GRAPHIC3 

21 FORL=0TO15 : GOSUB32 

22 FETCH V, IA, AD, BN 

23 NEXT 

24 FORL=15TOOSTEP-1 : GOSUB32 

25 FETCH V, IA, AD, BN 

26 NEXT 

27 RUN21 

28 REM ** ENSURE THAT RAM EXP. IS PRESENT ** 

29 A=DEC ( "DF06") : POKEA, 255 : IFPEEK (A) <>255THENPRINT"RAM NOT INSTALLED 
! ! " : END 

30 POKEA, 0 

31 A=DEC ( "DF00") :IF PEEK (A) AND16 THEN V=512:ELSE V=128:RETURN 

32 V=8192 : IA=V:MX=65536:BN=- (L>=8) :AD=L*V-MX*BN: RETURN 
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1.4.2 'ROM Expansion 



There are two other ways in which ROMs are used in the C-128 that are 
particularly interesting. In fact, they allow users to use ROMs for their own 
purposes. The two other ways in which ROMs are used in the 128 are for 
the Internal and External function ROMs. 

The Internal ROM is presently an empty socket that was designed to be used 
in the future. This ROM socket allows the use of up to 32K of memory area 
that is divided in two parts, $8000 -*$BFFF and $C000 - $FFFF. This area 
is accessible in BASIC with some configurations provided by the BASIC 
BANK command. 

The External ROM, on the other hand, is quite a bit more accessible and 
usable. One of the most widely used applications of the External function 
ROM is the game cartridge. The cartridge is inserted into the expansion port 
on die rear panel of the C-128. This port also allows the use of up to 32K of 
memory to be used by the cartridge in two parts: $8000 - $BFFF and 
$C000 - $CFFF. 



1.4.2.1 ROM Software Requirements 



In order to use the Intemal/Extemal ROM(s), certain requirements have 
been placed upon the software developer of the cartridge. Even though these 
requirements are simple to meet, the operating system is quite picky about 
them. When the computer is first turned on, a routine in ROM located at 
$E26B will check all four possible locations where the ROM (s) could be 
located. These locations are shown below in their priority of testing. 



BASIC BANK 


ADDRESS 


PHYSICAL ADDRESS 
TABLE (PAT) 


8 


$8000 


$0AC4 


8 


$C000 


$0AC3 


4 


$8000 


$0AC2 


4 


$C000 


$0AC1 
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The first thing that the routine will check for is the characters 'cbm' (not 
<SHLFT>ed). If a character in the ROM does not match, then the next ROM 
is tested. If there are no ROMs found with these characters, then the system 
will place zeros in location $0AC1 thru $0AC4 which are used by another 
routine which we will discuss in just a moment. 

If the characters 'cbm' are found to be in a ROM, then the routine will 
check to see if the ROM is an autostart ROM or not. If the value preceding 
the characters 'cbm' is a $01, then the routine will jump to the COLDSTART 
address of the ROM. 

This may start to sound complicated, but it's not. The format that the 
software in the C-128 requires is as follows. NOTE: The X could either be 
an 8 or a C depending which ROM address you are creating. 



ADDRESS 


DESCRIPTION 


$X000 - $X002 
$X003 - $X005 
$X006 

$X007 - $X009 


COLDSTART address to JMP to or JSR to. 
SPARE ADDRESS (Old 64 warm start address.) 
Auto start flag (l=auto start see text) 
Lower case text ' cbm ' 
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1.4.2.2 Auto -starting ROMs 



The KERNAL routine that checks to see if you want a ROM to AUTO 
start checks byte 6 of the ROM. If it contains a value of $01, then the 
routine terminates and JSRs to the ROM at the starting address. For 
example, if you had a game ROM inserted at $8000 in the external ROM 
and you wanted it to autostart, the ROM would be programmed as follows: 



ADDRESS 


SOURCE CODE 


DESCRIPTION 


$8000 - $8002 
$8003 - $8005 
$8006 

$8007 - $8009 
$800A 


JSR $800A 
JMP $9023 
.BYTE $01 
TXT 'cbm' 


Display start up screen. 

Enter the main loop of the program. 

Flag to auto start rom 

Flag to indicate a ROM is inserted here 

From this point on it ! s up to you 



1.4.2.3 Non-Auto-Starting ROMs 



Let's say, for example, you have developed a series of routines for 
performing structural analysis which you want to market and you wish to 
give the user the capability of using these routines in their own programs by 
just simply SYSing to them. One way of accomplishing this would be to 
create the ROM as explained above and place, for instance, your trademark 
character in place of the autostart byte, byte 6 in the ROM. 

For example, let's say you used the character '6', the routine at $E26B 
would find the ROM cartridge installed and log it in the Physical Address 
Table (PAT). The reason behind the PAT table is very simple. Once a ROM 
has been found when the system is first turned on or reset, the routine at 
$E26B will 'log' (see the table at 1.4.2. 1) it in its PAT table address. This 
table in turn will be used the next time the computer is reset. 

Upon powerup or reset, one of the first things that the computer does after 
some initializations is call another ROM routine called PHOENIX which 
will check for a boot sector on track 1 sector 0 on the disk. The very first 
thing the PHOENIX ($F867) routine will do is check the PAT table to see if 
any ROMs have been logged in and if so, it will JSR to the ROM in the 
same manner as an autostart. 
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Wedging Into BASIC 



BASIC 7.0 on the C-128 is one of the most powerful languages ever 
implemented on any of the Commodore computers. However, even with its 
powerful BASIC and all of the new commands, there are probably still 
some commands that you would like to have implemented. For instance, 
maybe some commands like KEYOFF and KE YON would be a nice addition. 
These two programs enable you to turn off the function keys and enable you 
to read and check each function key in your program, then restore them at 
any time to the original C-128 configuration. In this section we are going to 
create the KEYOFF and KEYON commands in a wedge example. 

Adding these commands and others at first may seem to be difficult to do. 
With the C-128 as is with the C-64, commands could be added by using the 
various VECTORS or the SYS command (limited on the C-128). However, 
the most popular way of wedging into BASIC is to wedge into the CHRGET 
(CHaRacter GET) routine. 



2.1 The chrget/chrgot Routine 



When the computer is first turned on or after the reset button is pressed, 
BASIC copies several routines from ROM (Read Only Memory) into RAM 
(Random Access Memory) to be used by the BASIC and KERNAL 
routines. One of these routines is called CHRGET. It is copied from ROM at 
$4279 - $4297 into RAM at $0380 to $039E. 

BASIC uses the CHRGET routine to get a character from the BASIC 
program memory or the input buffer. The input buffer is used to store 
characters from the keyboard until some action is taken to use these 
characters for other routines. Before we go any further, let's take a look at 
the CHRGET routine. 

On the next page is a disassembly of the CHRGET routine as it appears in 
memory in the C-128. 
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$0380: 


INC 


$3D 


$0382: 


BNE 


$0386 


$0384: 


INC 


$3E 


$0386: 


STA 


$FF01 


$0389: 


LDY 


#$00 


$038B : 


LDA 


($3D) ,Y 


$038D : 


STA 


$FF03 


$0390: 


CMP 


#$3A 


$0392: 


BCS 


$039E 


$0394: 


CMP 


#$20 


$0396: 


BEQ 


$0380 


$0398: 


SEC 




$0399: 


SBC 


#$30 


$039B: 


SEC 




$039C : 


SBC 


#$D0 


$039E : 


RTS 





NOTE: Refer to the disassembly of the CHRGET routine listed above when 
reading the step-by-step description of the routine. 



LOCATION 



DESCRIPTION 



$0380 - $0384 ; The TeXT PoinTeR (TXTPTR) is incremented by one 

;to point it to the next character in memory. 

;NOTE : The TeXT PoinTeR is stored in locations $3D/$3E in 
;LSB/MSB format and is used to hold the address of the 
/next character in memory. 

$0386 /This instruction is used to ensure that the character is 

/taken from RAM BANK 0 which is used for BASIC program 
/storage. If the CHRGET routine is entered here, it is 
/called CHRGOT (CHaRacter GOT) . CHRGOT accomplishes the 
/same job as CHRGET except the TeXT PoinTeR is not 
/incremented. 



$0389 - $038B /Here the character is taken from memory and stored into 
/the Accumulator. If the CHRGET routine is entered here, 
/it is called QNUM (Query for NUMber) . 

$038D /This instruction is used to ensure that the memory is 

/reconfigured to have all ROMs in place and RAM BANK 0 
/enabled which is the same thing as a BASIC BANK 14. 
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$0390 /If the character is a colon or greater, the routine 

/exits with the carry flag set. If the CHRGET routine is 
/entered at this point, it is called QNUM which stands 
/for Query NUMber . 

$0394 - $0396 /If character is a space, then the routine skips it and 
/gets the next character. 

$0398 - $039E /The character is checked to see if it is an ASCII digit 
/0-9 by first subtracting $30 and then $D0. If the char- 
acter is a digit, the carry flag will be cleared. If the 
/character is not a digit, then the carry flag is set. 



2.2 Wedging into the CHRGET Routine 



One of the reasons that you might want to wedge into the CHRGET routine 
is to implement a new command. However, before you can implement a 
new command, you must modify the CHRGET routine so that it checks for 
the new command. 

If you were to put a JMP or JSR to the routine for the new command at the 
beginning of CHRGET, the new routine would be executed each time that 
CHRGET was called but, not when CHRGOT was called. In addition, the 
new routine would have to increment txtptr and read in the next character 
itself. Consequently, in order to accomplish what you set out to do with the 
minimum amount of work, you will have to put the JMP to the new routine 
at $038D, where the new routine will be executed whenever CHRGET or 
CHRGOT is called and the current character that the operating system is 
about to process is already in the Accumulator. 

NOTE: Whenever you make any changes to CHRGET or CHRGOT, 
remember that you must perform the instructions that you replaced with the 
JSR or JMP. If you do not perform the instructions that were deleted, 
CHRGET will not function properly and it could cause the system to crash. 

To illustrate how to wedge into CHRGET to implement a new command, a 
routine was written to implement the KEYON and KEYOFF commands. As 
you will find by reading the ROM listings for the KEY command, even 
though these commands are tokenized by the BASIC operating system, they 
were not implemented when BASIC 7.0 was written. 
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The KEYOFF command redefines the eight function keys to the CHR$ 
values that are used for the function keys in the C-64. The KEYON 
command returns the definitions of the function keys to the C-128 KEY 
definitions. These commands may also be used in the PROGRAM (RUN) 
mode as well as the DIRECT mode. 

The starting address for the KEYON/KEYOFF routine is $0C00. However, 
the machine code from $0C00 to $0C09 puts the JMP $0C10 into$038D. 
The actual keyon/keyoff command routine starts at $0C10. Therefore, 
we will place a JMP $ 0 C 1 0 instruction at location $038D as shown below 
in the partial disassembly of the modified CHRGET routine. 



BEFORE THE 
MODIFICATION 



$0389: 


LDY 


#$00 


$038B : 


LDA 


($3D) . Y 


S038D : 


STA 


SFF03 


$0390: 


CMP 


#$3A 



AFTER THE 
MODIFICATION 


$0389: 


LDY 


#$00 


$038B : 


LDA 


( $3D) . Y 


$038D : 


JMP 


$0C1Q 


$0390: 


CMP 


#$3A 



The following disassembly and description are for the new routine that 
implements the KEYON/KEYOFF commands. Once you have typed in either 
the BASIC generator program or the source code using a machine language 
MONITOR, you must SYS DEC ( "0C00" ) to initialize the routine. 

Once the routine is initialized, the only way that you can interrupt the 
operation of the routine is to either shut the 128 off, press the RESET 
button, or go into the C-64 mode. To use the new commands, type 
KEYOFF to define the function keys to the C-64 definitions and type KEYON 
to return the function keys to the C-128 definitions. 



62 




Abacus Software 



C-128 BASIC 7.0 Internals 





ORG 


= $ocoo 








CHRGET 


* $0380 


;CHaRacter GET routine 




CHRGOT 


= $0390 


;CHaRacter GOT routine 




INDTXT 


= $03C9 


; INDirect load from TeXT 








/pointer 






PKYBUF 


= $1000 


/Programmable KeY 


BUFfer 


* — 


PKYDEF 


= $100A 


/Programable KeY DEFinitions 


★ 

★ 


Here is where 


we WEDGE into 


the CHRGET routine by 


★ 

* 


* 


inserting a JMP instruction 


to the new routine at 


★ 


* 


$038D . 






★ 




0C00: 


A0 


OC 




LDY 


#>WEDGE 


/Get the MSB and 


0C02 : 


A9 


10 




LDA 


#<WEDGE 


/The LSB of the address of 
/The new routine 


0C04 : 


A2 


4C 




LDX 


#$4C 


•Opcode for JMP 


0C06 : 


8E 


8D 


03 


STX 


$038D 


/Save the JuMP 


0C0 9 : 


8D 


8E 


03 


STA 


$038E 


/To the new routine 


0C0C: 


8C 


8F 


03 


STY 


$038F 


/In CHRGET 


0C0F: 


60 


it 




RTS 




/And exit to activate it 

ir 






* 

★ 


This 


section checks 


to see if 


* 

the command KEYON or * 






* 


KEYOFF was used. 




★ 




0C10 : 


C9 


F9 


WEDGE 


CMP 


#$F9 


/Is it the token for 'KEY'? 


0C12 : 


DO 


IF 




BNE 


NOTKEY 


/If not, then exit 


0C14 : 


A0 


00 




LDY 


#$00 


/If it is, then set up an 
/ Index to next character 


0C16 : 


C8 




SPACE 


INY 




/Increment index register 


0C17 : 


20 


C9 03 




JSR 


INDTXT 


/Get next character after 
/The token for 1 KEY * 


0C1A: 


C9 


91 




CMP 


#$91 


/Is next character the 
/Token for 1 ON * ? 


0C1C : 


F0 


36 




BEQ 


KEYON 


/Yes, then turn the 
/function key definition on 


0C1E : 


C9 


FE 




CMP 


#$FE 


/If not, is it the value 
/For a dual token ? 


0C20 : 


F0 


07 




BEQ 


CHKDUAL 


/Yes (first token for OFF) 



;then check the next token 
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0C22 : 


C9 


20 


CMP 


#$20 


;Is there a space between 
;Key and ON or OFF? 


0C2 4 : 


F0 


F0 


BEQ 


SPACE 


;If so, then skip it and get 



;The next character 




* At this point, the TOKEN for KEY was found, but the * 

* next character after it was not the TOKEN for * 

* either of the new commands. So a JuMP is made to * 

* execute the old KEY command. * 




0C26 : 4C 31 0C 



JMP OLDKEY 



★ * 

★ ★ 

* CHECK FOR THE DUAL TOKEN FOR KEYOFF * 

* * 







★ 


This 


section of 


machine code 


will check to see if * 






★ 


the 


token after 


$FE 


is $24. 


If it is, then the dual * 






* 

* 


command token is 


i for 


the new 


command KEY OFF. * 

•k 


0C29 : 


C8 






CHKDUAL 


INY 




/Move to character after 
















/The dual token 


0C2A: 


20 


C9 


03 




JSR 


INDTXT 


/Get the character 


0C2D: 


C9 


24 






CMP 


#$24 


/Is it the token for 'OFF'? 


0C2F : 


F0 


08 






BEQ 


KEYOFF 


/Yes, then turn the 
















/Function key definition off 


0C31 : 


A9 


F9 




OLDKEY 


LDA 


#$F9 


/Get the token for 'KEY 1 


0C33: 


8D 


03 


FF 


NOTKEY 


STA 


$FF03 


/Enable BANK 14 for CHRGET 


0C36 : 


4C 


90 


03 




JMP 


CHRGOT 


/Return to normal routine 



















* * 

* THE KEYOFF ROUTINE * 

★ ★ 

* This routine defines the eight function keys to the * 

* values that are used in the C-64. * 

* * 



★ 



★ 



0C39 : 20 80 03 KEYOFF JSR CHRGET ; Update TXTPTR 
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0C3C : 

0C3E : 
0C41 : 

0C44 : 
0C45 : 



0C4 7 : 
0C4 9: 
0C4B: 

0C4E : 



*_ 

★ 

★ 

★ 

★ 

★ 

* 

★ 

★ 



This section of machine code changes the eight * 
function key definitions to the values that are used * 
on the C-64 . * 



The following table give the definitions for the 
eight function keys after the KEYOFF command has 
been executed. 



KEYOFF FUNCTION KEY DEFINITIONS 



FI = CHR$ (133) 
F3 « CHR$ (134 ) 
F5 - CHR$ (135) 
F7 - CHR$ (136) 



F2 = CHR$ ( 137 ) 
F 4 = CHR$ (138) 
F6 = CHR$ (139) 
F8 = CHR$ (140) 





★ 


The 


following listed 


keys are also redefined by the * 




★ 


KEYOFF command. 




* 




★ 








★ 




★ 




SHIFT/RUN-STOP = CHR$(131) * 




★ 




HELP KEY = 


CHR$ (132 ) 


* 




★ 








★ 




★ _ 










AO 


09 




LDY 


#$09 


;Set up an index to the 












/Number of definitions 


B9 


DD 


C6 


NEXTKEY LDA 


$C6DD, Y 


/Get the 64 key 


99 


0A 


10 


STA 


PKYDEF, Y 


/configuration place it in 












/the key definition table 


88 






DEY 




/Move to next definition 


10 


F7 




BPL 


NEXTKEY 


/Continue until all 10 key; 




* 








/Are done 




★ 

★ 


Here 


★ 

! we reset the definition lengths of the eight * 




★ 

* 


function keys to 1. 




* 

* 


AO 


09 




LDY 


#$09 


/Index to number of keys - 


A9 


01 




LDA 


#$01 


/Length of key definition 


99 


00 


10 


NEXTKEY1 STA 


PKYBUF, Y 


/Set the key definition 












/Length to 1 


88 






DEY 




/Move to the next key 



65 



Abacus Software 



C-128 BASIC 7.0 Internals 



0C4F: 


10 


FA 


BPL 


NEXTKEY1 


/Continue until all 8 keys 
/Are done 


0C51 : 


4C 


5F 0C 


JMP 


EXIT 


/And exit 



THE KEYON ROUTINE 



* This routine will restore the eight function keys to * 

* their original definitions. * 

* ★ 

★ ★ 



0C54 : A0 


76 




KEYON 


LDY 


#$76 


/Set up an index to the 
/default key definitions 


0C56 : B9 


A8 


CE 


NEXTKEY2 


LDA 


$CEA8, Y 


/Get a chracter from the 
/Original definitions 


0C59 : 99 


00 


10 




STA 


PKYBUF, Y 


/Save them 


0C5C: 88 








DEY 




/Move to the next character 


0C5D : 10 


F7 






BPL 


NEXTKEY2 


/Continue until all of the 
/Keys have been restored 


0C5F : 20 


80 


03 


EXIT 


JSR 


CHRGET 


/Update TXTPTR 


0C62 : 4C 


80 


03 




JMP 


CHRGET 


/And exit to the normal 



; routine 



If you choose to use the BASIC generator program for the 
KEYON/KEYOFF routine, type the program exactly as it is listed here. 

10 REM KEYON/KEYOFF, BASIC 7.0 INTERNALS 
20 LN=160 : A=DEC ("0C00”) 

30 FORI=ATOA+ 102 STEP 8 
40 FORJ=0TO7 :READD$ 

50 V=DEC(D$) 

60 POKE I + J , V : CK=CK+V 
70 NEXTJ 

80 READCK$ : IF (CKAND255) ODEC (CK$) THEN 
PRINT "ERROR IN LINE "LN:GOTO150 
90 LN=LN+10 
100 CK=0 : NEXT I 

110 PRINT"DO YOU WANT TO SAVE THIS PROGRAM ?" 

120 GETKEYA$ : IFA$="N"THEN 140 

130 BSAVE "KEYON/KEYOFF. O", B0, P3072 TO P3175 

140 PRINT"TYPE 'SYS 3072' TO ACTIVATE" 

150 END 
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160 DATAAO, OC, A9, 10, A2, 4C, 8E, 8D, 6E 
170 DATA03,8D,8E,03,8C,8F,03,60, 9F 
180 DATAC9,F9,D0,1F,A0,00,C8,20, 39 
190 DATAC9,03,C9, 91,F0,36,C9,FE, 13 
200 DATAF0,07,C9,20,F0,F0,4C,31, 3D 
210 DATA0C,C8,20,C9,03,C9,24,F0, 9D 
220 DATA08, A9, F9, 8D, 03,FF, 4C, 90, 15 
230 DATA03,20,80,03,A0,09,B9,DD, E5 
240 DATAC6,99,0A, 10, 88, 10, F7, AO, A8 
250 DATAO 9,A9, 01, 99, 00, 10, 88, 10, F4 
260 DATAFA, 4C,5F,0C,A0,76,B9,A8, 28 
270 DATACE, 99, 00, 10, 88, 10, F7, 20, 26 
280 DATA80,03, 4C,80, 03, 6E,73,2D, 60 

After you have finished typing in the generator program, save a copy of the 
program to disk just in case an error causes the loss of the program in 
memory. Next, type RUN and press <RETURN>. After a few seconds, the 
program will ask if you wish to save the object code of the program. Type 
<Y> to save, <N> to run without saving. Once the keyon/keyoff 
program has been saved to the disk, type SYS 3072 or SYS 
DEC ( "0C00" ) and press <RETURN> to activate the new command 
routines. You can also attempt to use the BASIC command: 

BOOT "KEYON/KEYOFF" , B0 

It might even work, but there is a bug in the BOOT command which causes 
the system to break if you are using a disk drive that doesn't support the fast 
serial bus — see the BOOT routine for more details. 

If an error is found in the DATA statements, an error message will be printed 
indicating which DATA statement the error is in. Correct the error in the 
DATA statement, save a copy of the program to disk, and RUN the generator 
program again to save the KEYON/KEYOFF routine to disk. 

To test the new commands, enter KEYOFF and <RETURN>. Then type 
KEY and press <RETURN> to display the current function key definitions. 

What you should see is that the function keys are now defined to the same 
values as the C-64 function keys. To return the function keys to the initial 
C-128 definitions, type KEYON and press <RETURN>. To confirm that 
the function keys have been redefined to their original C-128 values, type 
KEY and press <RETURN> to display the current function key definitions. 



67 



Abacus Software 



C-128 BASIC 7.0 Internals 



The KEYON/KEYOFF routine does not save the current function key 
definitions before it redefines them to the C-64 values. Consequently, if you 
redefined the function keys and then did a KEYOFF and then a KEYON, the 
function keys would be returned to their original C-128 definitions and not 
to the definitions you had before you executed the KEYOFF command. 

If you want to use the new commands in your BASIC program, simply use 
the keyword as you would any other keyword that the C-128 uses. For 
example, this little program will display the function key definitions for the 
keys in both the KEYON and KEYOFF states. 

10 SCNCLR 
20 KEYOFF 

30 PRINT "C-64 DEFINITIONS" 

40 PRINT " " 

50 KEY 

60 KEYON 

70 PRINT: PRINT 

80 PRINT "C-128 DEFINITIONS" 

90 PRINT " " 

100 KEY 

The following BASIC program will demonstrate the use of the KEYOFF and 
KEYON commands. 

10 KEYOFF 
20 DO 

30 GETKEYA$ 

40 B=( (A<137) +85- (A-133) ) 

50 A=ASC(A$) 

60 IFA>13 6 THEN B=B+ (7+ (A>136) ) 

70 PRINT "THAT WAS THE F"CHR$ (A-B) " KEY" 

80 LOOP 

As you have seen, it is quite easy to wedge into the CHRGET routine to 
implement new commands and new routines. The number of routines that 
could be written to perform a function similiar to the KEYON/KEYOFF 
routine are only limited by the ambition and imagination of the programmer. 
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Graphics 



BASIC 7.0 offers a total of 10 graphics commands to greatly simplify the 
programming of High resolution (Hi-res) graphics on the Commodore 128. 
You can now draw lines, boxes, circles, etc., with just a few commands, as 
compared to the lengthy C-64 programs requiring peeks and POKES. But 
even with all of its specialized commands, BASIC 7.0 cannot cover all of 
the capabilities of the C-128. We'll cover the different aspects and 
capabilities of the C-128 graphics system in this chapter . 



3.1 Managing Memory 



The Commodore 128 has a total of 128K of RAM, which is divided into 
two RAM banks of 64K each. The reason for this is because the 8502 
microprocessor can only access 64K of RAM at any one time. Both the 
8502 and the VIC chip can each address a different 64K RAM bank. 

The VIC chip RAM bank is selected by the RAM configuration register at 
location $D506 (Bits 6 and 7). Bit 7 of this location is currently unused. To 
select RAM bank 1 for the VIC chip, bit 6 must be set to 1 and for RAM 
bank 0, bit 6 must be set to 0. 

The following BASIC and machine language instructions accomplish this: 
To select RAM bank 0 : 

BANK 15 : POKE DEC ("D50 6” ) , PEEK (DEC ("D506") ) AND 191 

In machine language : 

LDA #$00 ;Set the memory configuration 
STA $FF00 ; To BANK 15 to enable I/O 
LDA $D506 /Get the current value in $D506 
AND #$BF /Clear bit 6 to select RAM bank 0 
STA $D506 /And store it as the new value 
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To select RAM bank 1 : 



BANK 15 :POKE DEC ("D506") , PEEK (DEC ("D506") ) OR 64 
In machine language: 

LDA #$00 ;Set the memory configuration 
STA $FF00 ; To BANK 15 to enable I/O 
LDA $D506 ;Get the current value in $D506 
ORA #$40 ;Set bit 6 to select RAM bank 1 
STA $D506 /Store it as the new value 

Even though the 8502 can access 64K of RAM at a time, the VIC chip can 
only access 16K of memory at a time. Each of these 16K blocks of RAM 
are called VIDEO BANKS. So with 128K of RAM, that gives us 4 video 
banks in each 64K RAM bank for a total of 8 video banks. 

Two types of memory must be contained within a video bank; screen and 
character memory. You can select the video bank that the VIC chip will 
access by modifying bits 0 and 1 in location SDD00. 

In BASIC : 



POKE DEC ("DD00" ), (PEEK (DEC ("DD00") ) AND 252) OR X 

In machine language: 

LDA $DD00 ;Get the current value in $DD00 
AND #$FC /Clear bits 1 and 0 
ORA #$ X /Set the selected configuration 
STA $DD00 /And store the value back 

X = Value from the table below 

NOTE: To be able to read or write to RAM in the same area as ROM, you 
must select the memory configuration that contains RAM in these areas. 



VIDEO BANK MEMORY RANGE BUS. 

0 $0000-$3FFF 1 1 

1 $4000-$7FFF 1 0 

2 $8000-$BFFF 0 1 

3 $C000-$FFFF 0 0 



DEC. VALUE (X) 
3 DEFAULT 
2 
1 
0 
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3.1.1 Moving Screen and Character Memory 

When changing to a different video bank, you must move the location of 
screen and character memory. The C-128 uses the same register for moving 
screen and character memory as the C-64 ($D018), but the C-128's 
Interrupt driven screen editor uses the indirect registers at locations $0A2C 
(2604) and $0A2D (2605) to select the value in $D018. If you try to modify 
the register at $D018, the Interrupt routine will automatically reset it to the 
values that are at locations $0A2C and $0A2D. 

Consequently, if you want to program the VIC chip directly, you must 
disable the Interrupt routine by storing a 255 in location $D8 (216). Then 
you can program the VIC chip just as you would on the C-64. 

NOTE: The register at location $D8 (216) is automatically reset and the 
Interrupt driven screen editor is restarted when any BASIC graphics 
commands are executed. 

The values below are valid only if the Interrupt driven screen editor is on. 

Location $D8 (216) Bit 7 Multicolor Bitmap mode 

Bit 6 Split screen 

Bit 5 Standard Bitmap mode 

Location $0A2C(2604) Used for moving character and screen memory in 

text mode. 

Bits 7-4 control screen memory 

Bits 3-1 control character memory 

Location $0A2D(2605) Used for moving screen memory and the location 

of the Hi-res screen in the Bitmap mode 

Bits 7-4 control screen memory 

Bit 3 controls location of the Bitmap 

The BASIC and machine code instructions below move the screen memory. 
In BASIC : 

POKE V, (PEEK (V) AND 15) OR X 
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In machine language : 

LDA $V ;Get the current screen location 
AND #$0F ;Drop the old screen location 
ORA #$ X ; Replace it with the new location 
STA $V ;And store it back 

V = $0A2C for text mode and $0A2D for bitmap mode or $D018 if 
the Interrupt driven screen editor is disabled 
X = Value from the table below: 



Location of Screen Memory 



MEMORY RANGE BITS 7 




5 


4 DECIMAL VALUE (X) 


$0000-$03FF 


0 


0 


0 


0 


0 


$0400-$07FF 


0 


0 


0 


1 


1 6 DEFAULT 


$0800-$0BFF 


0 


0 


1 


0 


32 


$0C00-$0FFF 


0 


0 


1 


1 


48 


$1000-$13FF 


0 


1 


0 


0 


64 


$1400-$17FF 


0 


1 


0 


1 


80 


$1800-$1BFF 


0 


1 


1 


0 


96 


$1C00-$1FFF 


0 


1 


1 


1 


112 


$2000-$23FF 


1 


0 


0 


0 


128 


$2400-$27FF 


1 


0 


0 


1 


144 


$2800-$2BFF 


1 


0 


1 


0 


160 


$2C00-$2FFF 


1 


0 


1 


1 


176 


$3000-$33FF 


1 


1 


0 


0 


192 


$3400-$37FF 


1 


1 


0 


1 


208 


$3800-$3BFF 


1 


1 


1 


0 


224 


$3C00-$3FFF 


1 


1 


1 


1 


240 



NOTE: The value that results when you multiply the video bank number by 
the value $4000 (VB# * $4000) must be added to each of the starting 
addresses. 

For example, to generate the offset value for the first starting address, you 
would calculate the following: 

(VB# * $4000) = 2 * $4000 = $8000 

Next take the offset value and add it to the first address in the table to find 
the starting address of the RAM bank that is desired (SA + offset). 
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In our example, this would be: 

(SA + offset) = $0000 + $8000 = $8000 

In the standard character mode, the character set is located in ROM starting 
at location $D000. In the C-128, you have the ability to have the standard 
character set appear in any one of the 8 video banks by clearing the CHAREN 
bit (bit 2) in location 1. For example, this allows the VIC chip to 'see' the 
ROM character set in any video bank. If you wish to use your own 
character set, bit 2 of location 1 must be set to 1. Bits 3-1 in location 
$0A2C and $D018 are used to move the location of the character set. Bit 0 
is not used. 

The following BASIC and machine language instructions allow you to 
move character memory. 

In BASIC : 

POKE V, (PEEK (V) AND 240) OR X 

machine language : 

LDA $V ;Get the current character location 
AND #$F0 /Drop the old character location 
ORA #$ X /Replace it with the new location 
STA $V /And store it back 

V = $0A2C for text mode or $D018 if the Interrupt driven screen 
editor is disabled 

X = Value from the table on the next page: 



Location of Character Memory 



ME M ORY RAN G E BITS 1 



$0000-$07FF 0 
$0800-$0FFF 0 
$1000-$17FF 0 
$1800-$1FFF 0 
$2000-$27FF 1 
$2800-$2FFF 1 
$3000-$37FF 1 
$3800-$3FFF 1 



2 1 DEC I MAL VA LUE, IX) 

0 0 0 

0 1 2 

10 4 

11 6 

0 0 8 

0 1 10 

10 12 

11 14 
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NOTE: The value that results when you multiply the video bank number by 
the value $4000 (VB# * $4000) must be added to each of the starting 
addresses. 

For example, to generate the offset value for the first starting address, you 
would calculate the following: 

(VB# * $4000) = 2 * $4000 = $8000 

Next take the offset value and add it to the first address in the table to find 
the starting address of the RAM bank that is desired (SA + offset). 

In our example, this would be: 

(SA + offset) = $0000 + $8000 = $8000 



3.1.2 Color Memory 



In the C-128, the color memory occupies the range $D800 (55296) to 
$DBE7 (56295). This corresponds directly to the screen memory in the 
standard character mode. For example, with the text screen at location 
$0400-$07FF, location $D800 controls die color of location $0400, $D801 
controls the color of location $0401, etc. 

The C-128 has 2 color RAM banks that are controlled from bits 0 and 1 of 
location $0001. These 2 bits are labeled LORAM and HIRAM respectively. 
LORAM selects the color RAM bank that the 8502 microprocessor is 
currendy accessing and HIRAM selects the color RAM bank that the VIC 
chip is accessing. This allows you to change the color of the text screen or 
the multicolor bitmap instantiy. It also allows you to change the color of one 
screen while viewing another. Normally, the operating system will only 
allow you to use color RAM bank 0. Every time a graphics command is 
executed, the operating system automatically selects color RAM bank 0. 
However, there is a way around this. 

First, you must disable the Interrupt driven screen editor by storing a 255 
($FF) to location $D8 (216) so you can modify location 1 without the editor 
automatically resetting it. Then set bit 0 of the DDR register in location 0 to 
an input (0). This will not allow the operating system to modify the 
LORAM bit in location 1. The following program illustrates this process. 
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10 COLOR 3,1 : REM SET MULTICOLOR 2 TO BLACK 

20 GRAPHIC 3,1 : REM ENABLE MULTICOLOR BITMAP AND CLEAR IT 

30 BOX 3,90,90,60,60,45,1 :REM DRAW A BLACK BOX ON THE BITMAP 

40 POKE 216,255 :REM DISABLE INTERRUPT DRIVEN SCREEN EDITOR 

50 POKE 1, (PEEK ( 1) AND 252) OR 3 :REM ENABLE COLOR RAM 1 FOR VIC & 8502 

60 POKE 0, PEEK (0) AND 252 :REM SET DDR TO INPUT 

70 COLOR 3,7 : COLOR 2,2: 

REM SET MULTICOLOR 2 TO BLUE, MULTICOLOR 1 TO WHITE 
75 CIRCLE 2,75,75,23,23 :REM DRAW A WHITE CIRCLE 
80 BOX 3,90,90,60,60,45,1 :REM DRAW A BLUE BOX ON THE BITMAP 
90 POKE 0, (PEEK ( 0) AND 252) OR 3 : REM RESET DDR TO OUTPUT 
100 POKE 216,255 :REM DISABLE INTERRUPT DRIVEN SCREEN EDITOR 
110 DO :REM START OF LOOP 

120 POKE 1,PEEK(1) AND 252 :REM ENABLE COLOR 
130 SLEEP 1 :REM DELAY 

140 POKE 1, (PEEK ( 1) AND 252) OR 3 :REM ENABLE COLOR RAM 1 
150 SLEEP 1 :REM DELAY 

160 LOOP : REM CONTINUE 

This program first draws a black box on the screen whose color will be 
stored in color RAM 0. Then the LORAM and HIRAM bits are set to 1 to 
enable the 8502 to write to color RAM 1. This also allows the VIC to 
display color RAM 1. The corresponding bits in the DDR register at location 
$0000 are then set to input so the operating system does not default to color 
RAM 0. Then a white circle is drawn around a blue box which is in the 
same location as the black box, only the color of the blue box goes into 
color RAM 1, Then the program loops, first displaying color RAM 0 then 
color RAM 1. To stop the program, press <RUN/STOP> <RESTORE>. 



3.1.3 Moving the Bitmap Screen 



The standard bitmap screen on the C-128, as on the C-64, is 320 pixels 
wide by 200 pixels high. This adds up to a total of 64000 pixels that 
comprise a whole bitmap screen. Each pixel corresponds to one bit and 8 
bits make 1 byte, so a standard bitmap screen uses a total of 8000 bytes of 
memory. Since one video bank is 16K this means that there are only 2 
places in each video bank for a bitmap screen. Whether the bitmap resides in 
the upper or lower half of the video bank is dependent on bit 3 of location 
$0A2D or $D018. Even though there is room enough for 2 bitmaps in each 
video bank, you need IK of the video bank for the screen. So we can have 
only one bitmap per video bank, or a total of 8 bitmaps stored in memory. 
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The following instructions allow you to select the location of the bitmap. 
BASIC: 

POKE V, (PEEK (V) AND 247) OR X 

machine language : 

LDA $V 
AND #$F7 
ORA #$ X 
STA $V 

Where: V = $0A2D or $D018 if the Interrupt driven screen editor is disabled 
X = Value from the table below: 



Location of the Bitmap 



Value of bit 3 (X) 
Video. Bank 0 MU 1 LSI 



0 


$0000 


$2000 


1 


$4000 


$6000 


2 


$8000 


$A000 


3 


$C000 


$E000 



NOTE: When using any of the above information to move the bitmap or 
use a different video bank, remember that the operating system expects the 
bitmap to be at location $2000 in video bank 0 and its corresponding screen 
memory starting at location $0400. 

For example, when a graphics command such as draw is executed, the 
operating system always writes to location $2000 - $3FFF expecting the 
bitmap to be there. 

So if you move the location of the bitmap, BASIC 7.0 graphics commands 
cannot be used to draw on the hi-res screen. 
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3.2 Hi-res Graphics from Machine Language 



Although bXSIC 7.0 has some powerful graphics commands, these same 
routines can easily be used from machine language. This keeps you from 
having to write your own graphics routines from scratch. The following 
table shows some of the different graphics routines accessible from machine 
language, and the appropriate parameters for each. 



ACTION BASIC EQUIVALENT ADDRESS PARAMETERS 



Plot a point DRAW 1,X,Y 



$9BFB $1131, $1132 X Coordinate 
$1133, $1134 Y Coordinate 
$116B 1 = Double width 

0 = Single width 



Draw a line 



DRAW 1, X, Y TO X, Y $9B30 



$1131 , $1132 
$1133, $1134 
$1135, $1136 
$1137, $1138 
$11 6B 



Start X Coord. 
Start Y Coord. 
End X Coord. 
End Y Coord. 

1 = Double width 



0 = Single width 



Draw a box 



BOX 1, XI, Yl, X2 , Y2 



$62D7 $1150, $1151 

$1152, $1153 
$115C, $115D 
$115E, $115F 
$1154 

X Register 



Top right X Coord. 
Top right Y Coord. 
Bottom rt X Coord. 
Bottom rt Y Coord. 
Rotation angle 
Fill flag 
0 = No fill 



Fill area PAINT 1,X,Y 



$61C0 Accumulator Mode flag 128 = Fill 
an area defined by non-background source 
$1131, $1132 X Coordinate 
$1133, $1134 Y Coordinate 



Clear screen SCNCLR (mode) $6A92 X Register Screen to clear 

0 = 40 Col. text 

1 = Standard Bitmap 

2 = Split-screen 

Std. Bitmap 

3 = Multicolor Bitmap 

4 = Multicolor Split 

5 = 80 Col. text 
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ACTION BASIC EQUIVALENT ADDRESS PARAMETERS 

Print chars. CHARI, Col, Row, Str $68DB Accumulator Character to output 

X Register Column 
Y Register Row 

$113D Reverse Flag 

128 = Reverse Chars. 

0 = Normal Chars. 

$1168 Page number (MSB) of 

character set in ROM. 
Ex: $D0 for the standard character set 

NOTE: On all of the above, location $83 should contain the color source 
number. All X and Y coordinates are stored in LSB, MSB format. 

The following routine is the equivalent of the BASIC 7.0 command 
BOX 1 , 20,20,50,50,45,1 , which draws a filled box that is rotated 
at a 45 degree angle on the hi-res screen. 



LDX 

JSR 

LDA 

STA 

LDA 

STA 

STA 

STA 

STA 

LDA 

STA 

STA 

LDA 

STA 

STA 

LDA 

STA 

TAX 

JMP 



#$01 /Select standard bitmap 
$6A92 /Clear it 



#$01 

$83 /Select color source 1 
#$00 

$1151 /Set the MSB of the 
$1153 /Coordinates 
$115D /To zero 



$115F 

#$14 

$1150 

$1152 

#$32 

$115C 

$115E 

#$2D 

$1154 

$ 62D7 



Set the top right 
X coordinate 

And the top right Y coord, to 20 

Set the bottom right 

X coordinate and 

The bottom right Y coord, to 50 

Set the rotation angle 

To 45 degrees 

Select Fill 

Draw the BOX 



Of course, these are not the only graphics routines that can be called from 
machine language. There are several routines that can be used. They can be 
found in commented form in the ROM listings for $6000 and $9000. 
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The BASIC 7.0 ROM Listing 



This is probably the longest single chapter you'll ever see, encompassing 
about 500 pages. This disassembled and commented ROM listing details the 
BASIC commands, and how the operating system determines which 
command or function is called, as well as when each command or function 
is required. 

Since different versions of the C-128 operating system have been released, 
your addresses and jumps may occasionally be different from this listing. 
To confirm any discrepancies, examine your own BASIC 7.0 with the 
machine language MONITOR equipped on your C-128: 

1. Turn on your C-128. 

2. Press function key 8 (<SHIFT>-<F7>), or type MONITOR and 
press <RETURN>. 

3. To display a memory range in BASIC 7.0, use the M (memory) 
command. For example, to see memory from $45 IE to $4576, 
type M F451E F4576onthe keyboard and end this input with 
<RETURN>. 

4. A more detailed listing can be seen by using the D (disassemble). 

To disassemble machine code into assembly language mnemonics 
and operands from $4000 to $401 A, type D F4000 F401A 
<RETURN>. The disassembled code also includes the 
hexadecimal values of the code. 

5 . To exit the monitor and get back to BASIC, type X <RETURN>. 

If you have any questions about the MONITOR, refer to Appendix J of the 
Commodore 128 System Guide. 
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★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★I******* 
★ * 

* COMMODORE 128 ROM LISTINGS * 

★ * 

* BASIC ROM LOW ( $4000 - $7FFF ) * 



********************************************************* 

★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★a"** 
* * 

* KERNAL TO BASIC JUMP ADDRESSES * 

* * 

* Addresses $4000, $4003, and $4006 are used as jump * 

* addresses for the KERNAL so that it may allow * 

* the BASIC operating system to take control. * 

* * 
***★**★★★****★***★*★★★**★★★**★★*★★**★★*★★★★**★*★★***★*★*★ 



ADDR 


SOURCE 


, CODE 


COMMENTS 


4000: 


JMP 


$4023 


;Cold start entry point 


4003: 


JMP 


$4009 


/Warm start entry point 


4006: 


JMP 


$A84D 


/Interrupt ReQuest entry point (BASIC IRQ) 



★ ★ 

* WRMSTRT * 

★ ★ 

* WaRM STaRT entry point * 

★ * 

* This routine resets the I/O channels to the screen * 

* for output and the keyboard for input, sets up the * 

* sprite and sound tables, sets up the Memory * 

* Management Unit for BASIC, resets the string stack, * 

* and then prints the READY message to the screen. * 

* This routine is also jumped to when the RUN/STOP * 

* RESTORE key combination is used, when the C-128 

* is first turned on, and when you exit the monitor. 

* NOTE: You may wish to change the jump address at 

* $0A00 to point to $40FF or $401C to prevent the 

* monitor from resetting these pointers. 



'k-k + 'k + ir'k'k'k'k-icit'kit'kit-k'k-k'kitit'k-kirir-k'kir'k'kicicicit-ktcitititit'k'kit'k-kititie-kic'k'k’kickic 
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4009: 


JSR 


$FFCC 


/Clear any open channels/ Set system to default 
/I/O (screen as output and keyboard as input) . 


400C : 


JSR 


$4 17A 


/Set up MMU configuration registers for the 
/BASIC interpreter 


400F : 


JSR 


$4 18D 


/Clear sprite speed/direction table 


4012: 


JSR 


$4112 


/Set up the default values for sound registers 


4015: 


JSR 


$5238 


/Reset the string stack pointer to $1B 


4018: 


LDA 


#0 


/Set the current input device 


401A: 


STA 


$15 


/for screen prompting 


401C : 


CLI 




/Allow background jobs to start (INTERRUPTS) 


401D : 


JMP 


$4D37 


/Print READY to the screen, enable KERNAL 
/Messages and disable control messages 


4020: 


.BYTE 


$0 , $FF, $FF 


/Spare jump address (unused) 



********************************************************* 



* 



* 



* CLDSTRT 

* 



* 

* 



* CoLD STaRT entry point 

* 



* 

* 



* This routine sets up the Memory Management Unit and * 

* various BASIC vectors and rouines, prints the * 

* start-up message to the screen, and then has the * 

* KERNAL routine PHOENIX check for an auto boot disk * 

* in DRIVE 0, DEVICE 8. * 

* * 

* This routine is normally called when the 128 is * 

* first turned on, and also whenever the reset button * 

* is depressed. * 

* * 






4023: 


JSR 


$417A 


/Set up Memory Managment Unit 


4026: 


JSR 


$4251 


/Set up the vector tables for BASIC 


4029: 


JSR 


$4045 


/Set up the various jmp/zero page RAM routines 


402C : 


JSR 


$419B 


/Print the CBM and MICROSOFT display messages 


402F : 


LDA 


$0A04 


/Set bit 0 so the KERNAL IRQ 


4032: 


ORA 


#1 


/Routine will call the 


4034: 


STA 


$0A04 


/BASIC IRQ routine for GRAPHICS/SOUND/LIGHT PEN 


4037: 


LDX 


#$03 


/Set up the system restart vector to 


4039: 


STX 


$0A00 


/$4003 (normal warm start) 


403C : 


LDX 


#$FB 


/Reset the stack pointer 


403E : 


TXS 






403F : 


JSR 


$FF56 


/Check TRACK 1 SECTOR 0 for auto boot info. 


4042: 


JMP 


$401C 


/Jump to BASIC warm start to restart the 
/background Jobs and print the READY message to 



/the screen 
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★******************************************************** 
★ ★ 

* INIT * 

* INITialize registers * 

* ★ 

* This routine is called by the CLDSTRT routine above * 

* to initialize all of the BASIC ZERO PAGE address * 

* which have a fixed value. Some of these routines * 

* are the USER call routine and the CHRGET routine. * 

* NOTE: See the routine block notes below * 

* ★ 
★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★■A* 

★ * 

★ ★ 

* This routine sets up jump for function evaluation * 

* and the USR vector. * 

* * 

★ * 

4045: LDA #$4C ;Set up the jump for function evaluations 

4047: STA $56 

4049: STA $1218 ;Set up the jump for the USR jump address 

★ — ★ 

* * 

* Point the USR vector to * 

* an 'ILLEGAL QUANTITY' error message * 

* * 

* — * 

404C: LDA #$28 

404E : LDY #$7D 

4050: STA $1219 

4053: STY $121A 

★ — ★ 

★ * 

* Set up the vector for converting a floating point * 

* number to an integer ($849F) * 

* * 

* * 

4056: LDA #$9F 

4058: LDY #$84 

405A: STA $117A 

405D : STY $117B 
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4060: 
4062: 
4064 : 
4067: 



406A: 
406C : 
40 6F : 
4072: 
4073: 



4075 

4078 

407A 

407C 

407F 

4082 

4084 

4086 

4088 

408B 

408E 

4091 

4094 

4097 

409A 

409D 



* * 

* * 

* Set up the vector for converting an integer to * 

* a floating point number ($793C) * 

* * 

* * 



LDA #$3C 
LDY #$79 
STA $117C 
STY $117D 



* * 

★ * 

* Copy ROM addresses $4278-$42CD to RAM: $037F-$03D4 * 

* * 

★ * 

LDX #85 /Copy 85 bytes 

LDA $4278, X /Copy subroutines in ROM to $037F-$03D4 

STA $037F, X 

DEX 

BNE $406C 



★ — — 

★ 

* Initialize various registers 

* 

* — 



STX 


$03DF 


/Clear the OVERFLOW marker for FAC1 


STX 


$15 


/Set up the screen prompting flag 


STX 


$1A 


/Set the MSB of the last descriptor to zero 


STX 


$116F 


;Turn off the TRACE mode 


STX 


$1C00 


/1st END OF LINE for BASIC. Note: You must do 
/this if you relocate BASIC 


STX 


$76 


/Clear the HI-RES flag 


STX 


$74 


/Clear the offset value for the AUTO command 


STX 


$75 


/Clear MSB of the AUTO command offset 


STX 


$116B 


/Double width off 


STX 


$116A 


/Screen scaling to 320 * 200 


STX 


$116C 


/Clear the temporary pointer for FILL 


STX 


$121B 


/Clear the initial value for RND command 


STX 


$011C 


/Clear MSB for the BASIC BSAVE command 


STX 


$1276 


/Clear the BASIC COLLISION 1 interrupt 


STX 


$1277 


/Clear the BASIC COLLISION 2 interrupt 


STX 


$1278 


/Clear the BASIC COLLISION 3 interrupt 



★ 

* 

★ 
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40A0 

4 0 A3 

40A5 

40A8 

40A9 

40AB 

40 AC 

4 OAF 

40B2 

40B4 

40B7 

40B9 

40BB 

40BD 

40BF 

40C1 

40C3 

40C6 

40C8 

4 OCA 

40CC 

40CE 

40D0 

40D2 

40D4 

40D6 

40D8: 

40DA 

40DC 

40DE 

40E1 

40E4 

40E6 

40E8 

40EA 



40EC: 
40EE : 
40F0 : 
40F1 : 
40F 4 : 



Software 
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STX 


$127F 


/Clear the INTERRUPT IN PROGRESS flag 


LDY 


#$58 


/Clear the sprite data 


STA 


$117E, Y 


/Area with $E6 


DEY 






BPL 


$40A5 




INX 






STX 


$01FD 


/Useless code. 


STX 


$01FC 


/unused by any routines 


LDX 


#15 


/BANK 15 for 


STX 


$03D5 


/BASIC SYS, POKE, PEEK, and WAIT commands 


LDX 


#13 


/Medium gray 


STX 


$86 


/Foreground color 


LDX 


#1 


/Black 


STX 


$84 


/Multicolor 1 foreground 


LDX 


#2 


/White 


STX 


$85 


/Multicolor 2 foreground 


JSR 


$6A5C 


/Set up the bkground/border & mult. /border 


LDX 


#$1B 


/Start of temporary string 


STX 


$18 


/Stack for string descriptors 


LDX 


#$01 


/Set the START of BASIC to $1C01 


LDY 


#$1C 




STX 


$2D 


/Save it to TXTTAB 


STY 


$2E 




LDA 


#$00 


/Set the START of BASIC VARIABLES 


LDY 


#$04 


/To $0400 in RAM BANK 1 


STA 


$2F 




STY 


$30 




LDA 


#$00 


/Set the highest address 


LDY 


#$FF 


/Available to BASIC to $FF00 


STA 


$1212 


/ ( RAM BANK 0 ) 


STY 


$1213 




LDA 


#$00 


/Set the highest address 


LDY 


#$FF 


/Available to BASIC strings 


STA 


$39 


/and variables to $FF00 


STY 


$3A 


/ ( RAM BANK 1 ) 




★ 

★ 

* _ 


Set up 


$07F8 - $07FF for Sprite ID area (Data Table) 


LDX 


#$3F 


/Starting value to be stored at $07FF 


LDY 

TXA 


#7 


/Number of bytes to do 


STA 

DEX 


$07F8 , Y 


/Store value in SPRITE ID area address 
/Decrement the value to be stored by one 
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40F5: DEY /Decrement the index 

40F6: BPL $4 0F0 /Continue until done 

★ 
★ 
★ 
★ 
* 



★ 

* Clear the sprite speed/direction table 

★ 



40F8 


LDA 


#0 






4 OF A 


LDX 


#$6C 


/For 109 bytes to clear 




40FC 


STA 


$117E,X 


/Clear area 




40FF 


DEX 








4100 


BPL 


$40FC 


/Continue until done 




4102 


JSR 


$4112 


/Set up default values for the 


sound registers 


4104: 


LDA 


#$D0 


/Set up the Page number for 




4107: 


STA 


$11EC 


/Uppercase/Graphics character 


set 


410A: 


LDA 


#$D8 


/Set up the Page number for 




410C: 


STA 


$11EB 


/Lowercase/Uppercase character 


set 


410F : 


JMP 


$51D9 


/Do a BASIC NEW command 





This routine sets up the various default values 
used for the PLAY command. It also sets up the SID 
sound registers . 



4112 


LDA 


#$20 


/Set up Note TIME to 




4114 


LDY 


#1 


/The length 




4116 


STA 


$1229 


/Of a sixteenth-note 




4119 


STY 


$122A 


/As the default value 




411C 


LDA 


#4 


/Set the default 




411E 


STA 


$122B 


/Octave to 4 in OCTAVE 




4121 


LDA 


#16 


/ Set up 




4123 


STA 


$1222 


/TEMPO rate to 16 




4126 


LDA 


#0 


/Turn off 




4128 


STA 


$D404 


/VOICE 1 




412B 


STA 


$D40B 


/VOICE 2 




412E 


STA 


$D412 


/VOICE 3 




4131 


STA 


$12FD 


/Enable the BASIC IRQ 


routine 








/GRAPHICS/SOUND/LIGHT 


PEN 


4134 


LDA 


#15 






4136 


STA 


$1274 


/Set up default 




4139 


STA 


$1275 


/FILTER values 




413C 


STA 


$D4 18 


/Set sound VOLume to maximum 
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★ 



* 



* The default sound values are set up in the memory 





★ 


locations as listed 


below. 


* 




★ 








★ 




★ 


LOCATIONS 


DESCRIPTION 


★ 




★ 


$123F - 


$1248 


ATTACK, DECAY 


★ 




* 


$1249 - 


$1252 


SUSTAIN, RELEASE 


★ 




★ 


$1253 - 


$125C 


WAVEFORM 


★ 




★ 


$125D - 


$1266 


PULSE WIDTH LSB 


★ 




* 


$1267 - 


$1270 


PULSE WIDTH MSB 


★ 




★ 








★ 




*_ 


— 






_ * 


413F : 


LDY 


#$1D 








4141: 


LDA 


$7011, Y 


; Set UP 


ATTACK, DECAY 




4144: 


STA 


$123F, Y 


/SUSTAIN 


, RELEASE and WAVEFORM 




4147: 


DEY 










4148: 


BPL 


$4141 










Set up pulse width MSB 




414A : 


LDX 


#9 










414C : 


LDA 


$702F,X 


; Set up 


PULSE WIDTH 




414F : 


STA 


$1267, X 










4152: 


DEX 












4153: 


BPL 


$4 14C 










4155: 


STX 


$1285 


/Clear 


TIME 


STORAGE 


low 


4158: 


STX 


$1286 


/Clear 


TIME 


STORAGE 


med 


4 15B : 


STX 


$1287 


/Clear 


TIME 


STORAGE 


high 


415E : 


STX 


$1224 










4161: 


STX 


$1226 










4164 : 


STX 


$1228 











★ * 

★ ★ 

* Initialize SID VOICES 1-3 * 

* * 



4167 : 


LDY 


#2 


/Counter 


to voice number 


4169: 


STY 


$122F 


/Save it 


as a counter 


416C : 


LDX 


#0 
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416E 

4171 

4174 

4176 

4179 



417A 

417D 

417F 

4182 

4185 

4186 
4188 



BITS 

4189: 
418A: 
418B: 
418C : 



JSR $6EB2 /Initialize voice w/ values stored $123F-$1271 

DEC $122F ;To next voice 

BPL $416C 

INC $122F /Counter to zero 

RTS 






★ * 

* SETMMU * 

★ * 

* SET up the Memory Management Unit * 

★ * 

* Configure the MMU registers A-D. * 

★ * 






JSR 


$A845 


/Do a BASIC BANK 15 command 


LDX 


#3 


/Index pointer 


LDA 


$4189, X 


/Preset values in ROM 


STA 


$D501 , X 


/To set up MMU registers 


DEX 




/Do 4 registers 


BPL 


$417F 




RTS 




/And exit 



★a******************************************************* 



* 



* 



* MMU TAB 

★ 



* 

* 



* Memory Management Unit TABle * 

★ * 

* Table for preconfiguration of PCRA through PCRD * 

* * 






76543210 



BYTE 


$3F 


/BASIC BANK 


0 


% 


00111111 


BYTE 


$7F 


/BASIC BANK 


1 


% 


01111111 


BYTE 


$01 


/BASIC BANK 


14 


% 


00000001 


BYTE 


$41 


/RAM BANK 1, 


BASIC, 


KERNAL, CHR ROM % 


01000001 



/The same as BASIC BANK 14 except 
/RAM BANK 1 
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★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★•A* 



★ ★ 

* SETSPR * 

★ ★ 

* SET speed/direction table for the SPRites. * 

★ * 






418D : 


LDA 


#0 


418F : 


LDY 


#7 


4191: 


LDX 


$ 6DD9, Y 


4194: 


STA 


$117E, X 


4197: 


DEY 




4198: 


BPL 


$4191 


419A: 


RTS 





/Index pointer 
/Pointer to register 
/Clear register 
/Do 8 registers 

/And exit 



★ ★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★■A 1 

★ ★ 

* STRTMSG * 

★ ★ 

* Print the STaRTup MeSsaGe to the screen * 

★ ★ 
★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★•A* 



419B 


LDY 


#0 






419D 


LDA 


$4 IBB, Y 


/Get a byte of the startup message 


41A0 


CMP 


#'0' 


/New line flag? 




41A2 


BNE 


$41B2 


/No, then branch to print the 


character 


41A4 


BIT 


$D7 


/Check to see if we* re in 40- 


or 80-column mode 


41A6 


BPL 


$41B5 


/ Branch if in 40-column mode 






* If you are in the 80-column mode, this routine * 

* will print nineteen spaces before the start of * 

* each new sentence to center the text on the 80- * 

* column screen. * 

* * 

* * 



41A8 : 


LDX 


#19 


/Nineteen spaces 


41AA: 


LDA 


#32 


/To the screen 


41 AC : 


JSR 


$9269 


/Continue to print one space at a time 


41AF : 


DEX 




/Until the X register equals 


41B0 : 


BNE 


$41AA 


/Zero . 


41B2 : 


JSR 


$9269 


/Print the character in the accumulator 


41B5 : 


INY 




/Increment the index pointer 
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41B6: 


CPY 


#$96 


;97 characters printed yet? 




41B8 : 


BNE 


$419D 


;No, then continue printing 




41BA: 


RTS 




;Exit the routine 






********************************************************* 




★ 






★ 




★ 




MSGTBL 


★ 




★ 






★ 




★ 


The 


startup Message TaBLe is as follows: 


★ 




★ 






★ 




********************************************************* 


41BB : 


.BYTE 


$93 


/Clear the screen 




41BC: 


.BYTE 


$0D 


; <CR> 




41BD : 


TXT 


i @ i 


/Start of line pointer 




41BE : 


TXT 


i 


commodore basic v7.0 122365 bytes free* 




41E5 : 


.BYTE 


$0D 


/ <CR> 




41E6 : 


TXT 


i @ i 


/Start of line pointer 




41E7 : 


TXT 




(c) 1985 commodore electronics, ltd.' 




420D : 


.BYTE 


$0D 


/ <CR> 




420E : 


TXT 


'0' 


/Start of line pointer 




420F : 


TXT 


i 


(c) 1977 microsoft corp. 1 








$0D 


/ <CR> 




4230: 


TXT 


i @ i 


/Start of line pointer 




4231: 


TXT 


t 


all rights reserved' 




424F : 


.BYTE 


$0D, $00 


/ <CR>, End of text flag 






********************************************************* 




★ 






★ 




* 

"k 




COPYVEC 


* 

★ 




* 

4 - 


COPY the system VECtor tables to RAM 


* 

* 






4251: 


LDX 


#17 


/Copy 18 bytes or 9 vector addresses to 


RAM 








/Starting at $0300 




4253: 


LDA 


$42 67 , X 


/Get the BASIC vectors from ROM 




4256: 


STA 


$0300, X 


/And store them to RAM 




4259: 


DEX 




/Do 18 bytes 




425A: 


BPL 


$4253 
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425C : 
425E : 
4261: 
4263: 
4266: 



4267 : 
4269: 
426B: 
42 6D: 
426F : 
4271: 
4273: 
4275: 
4277: 



********************************************************* 
★ ★ 

* This routine sets up an indirect jump vector at * 

* $02FC/$02FD to jump to $4C78. When entering this * 

* routine, if the carry is set a SYNTAX ERROR will * 

* result. If the carry is clear, the VALTYP flag * 

* at $0F is checked for to see if the type is numeric. * 

* If the type is not numeric, a SYNTAX ERROR will * 

* result. * 

* ★ 

********************************************************* 



LDA 


#$78 


;Low byte of address 


STA 


$02FC 


/Store it 


LDA 


#$4C 


/High byte of address 


STA 


$02FD 


/Store it 


RTS 




/And exit 






★ ★ 

* VECTBL * 

* ★ 

* system VECtor TaBLe * 

★ ★ 



* This table contains the vectors for some of the * 

* important routines used by BASIC. This table is * 

* copied to RAM starting at $0300. * 

* ★ 

********************************************************* 



DA 


$4D3F 


/Vector: 


Error message routine (IERROR) 


DA 


$4DC6 


/Vector : 


Read/exec, basic line (IMAIN) 


DA 


$430D 


/Vector: 


Convert interpreter code (ICRNCH) 


DA 


$5151 


/Vector: 


Convert to text (list) (IQPLOP) 


DA 


$4AA2 


/Vector : 


Execute the keyword (IGONE) 


DA 


$78DA 


/Vector: 


Evaluate expression (IEVAL) 


DA 


$4321 


/Vector: 


Conversion routine (ICON) 


DA 


$51CD 


/Vector: 


Escape list (IESLST) 


DA 


$4BA9 


/Vector: 


Execute escape (ISERROR) 
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CHRGET 

CHaRacter GET routine 
Transferred into RAM located at $0380 



* This routine will read one character at a time from * 

* the memory location pointed to by TXTPTR ($3D/$3E) . * 

* Before each character is read, this routine will * 

* increment the TXTPTR, and will fall through to the * 

* CHRGOT routine below. * 



★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★it* 



4279: 


INC 


$3D 


/Increment BASIC text pointer LOW byte 


427B: 


BNE 


$427F 


;If low byte is not equal to zero, 
/Then don’t increment the high byte 


427D : 


INC 


$3E 


/If low byte is equal to zero, 
/Then increment the high byte 



* * 



* CHRGOT * 

★ ★ 

* CHaRacter GOT routine * 

★ ★ 

* Transferred into RAM located at $0386 * 

★ ★ 

★ ★ 



* This routine reads the character that TXTPTR points * 

* to plus the index register. Then it will fall through* 

* to QNUM. This routine also will read the byte from * 

* BANK 0 and return to BANK 14. * 

* * 



★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★a********** 



427F : 


STA 


$FF01 


/Enable BASIC BANK 0 


4282: 


LDY 


#0 


/ Index pointer 


4284: 


LDA 


<$3D ) ,Y 


/Get character from BASIC text 


4286: 


STA 


$FF03 


/Enable BASIC BANK 14 
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★ * 

* QNUM * 

★ ★ 

* Query NUMber routine * 

★ * 



* CARRY FLAG - is cleared if the character is an ASCII * 

* digit 0-9. If it is not a digit, the carry flag is * 

* set . * 

* ★ 

* ZERO FLAG - is set if the character is the statement * 

* terminator ($00) , or if it is the statement chain * 

* flag which is the colon ' : ' . The zero flag is * 

* cleared if the character is neither the statement * 

* terminator or the chain flag. * 

* ★ 
★ ★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★■it* 



4289: 


CMP 


#' : ’ 


/If character greater than 1 :' 
/The carry flag is set 


then 




428B: 


BCS 


$4297 


/If char, is greater than or equal to ' 


: 1 branch 


428D : 


CMP 


#$20 


/Check to see if the character 


is a space 


42 8F : 


BEQ 


$4279 


/If it is then skip it and get 


the next 


char . 


4291: 


SEC 




/Set the carry for subtraction 






4292 : 


SBC 


#'0' 


/Subtract to make true numbers 


if they 


are 0-9 


4294 : 


SEC 




/Set the carry for subtraction 






4295: 


SBC 


#$D0 


/If the character is less than 
/Then set the carry flag 


0 , 




4297 : 


RTS 




/The carry flag is cleared for 


numbers 


on exit 



★ ★ 

* BASIC INDSUB RAM 0 ROUTINE * 

★ * 

* INDirect SUBroutine load from RAM bank 0 * 



This routine reads a byte from BANK 0 and then 
returns to BANK 14. 

EXAMPLE: To get a byte from location $0100, BANK 0, 
store the LOW/HIGH byte address ($00, $01) to any 
ZERO-PAGE location such as $61, $62. Then put the 
low byte of the zero - page address in the 
accumulator. In this case, it would be $61. 

Then put the index to the byte wanted in the Y 
register, and JSR to this routine. On return, 
the byte wanted will be in the accumulator. 
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* NOTE: These steps also apply to the next two 

* routines. 

* 



★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★a-********************** 
★ ★ 
* Stored in RAM at $039F * 



★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★I**************** 



4298: 


STA 


$03A6 


;Zero page location to load from 


429B: 


STA 


$FF01 


/Enable BASIC BANK 0 


429E : 


LDA 


($00) ,Y 


;Get a byte from BANK 0 at indirect 
; $03A6 


42A0 : 


STA 


$FF03 


/Enable BASIC BANK 14 


42A3 : 


RTS 




/And exit 



********************************************************* 
★ ★ 

* BASIC INDSUB RAM 1 ROUTINE * 

★ * 

* This routine reads a byte from BANK 1 and then * 

* returns to the RAM BANK 1, BASIC, KERNAL and I/O * 

* memory configuration. * 

* * 
********************************************************* 



* * 

* Stored in RAM at $03AB * 

★ ★ 






42A4 : 


STA 


$03B2 


;Zero page location to load 


. from 


42A7 : 


STA 


$FF02 


/Enable BASIC BANK 1 




42AA: 


LDA 


($00) ,Y 


/Get a byte from BANK 1 at 


indirect address in 








/ $03A6 




4 2 AC: 


STA 


$FF04 


/Enable RAM BANK 1, BASIC, 


KERNAL, and Char. ROM 


42AF : 


RTS 




/And exit 





********************************************************* 
★ * 

* BASIC INDIN1 RAM 1 ROUTINE * 

★ * 

* This routine reads a byte stored in BANK 1 from the * 

* location that is stored in $24, $25 + the index to * 

* byte in the Y register. The value of the byte * 

* is returned in the accumulator. After this has * 

* been completed, this routine returns to the BANK 15 * 
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